From 69948cb151318718c1e05620363a6e4f9c902614 Mon Sep 17 00:00:00 2001 From: Filip Leonarski Date: Wed, 18 Nov 2026 08:20:18 +0100 Subject: [PATCH 01/41] FPGAImagePuller back: rugnux live on the FPGA path through the stream receivers FPGAImagePuller (rc186's, as 0d26ecd13 left it, with 6b485e57c: every slot and its compressed-image buffer made up front) takes the card's frames, assembles and compresses them and hands them on in image order as an ImagePuller, so a PSI collection runs through the same stream receivers as a DECTRIS one. JFJochReceiverService::UseFPGAImagePuller(FPGAImagePullerUse, slots): - RugnuxLive (default): a PSI collection analysed by rugnux live goes through the puller to JFJochReceiverRugnuxStills, or JFJochReceiverRugnuxRotation for a rotation (which the FPGA path had no live analysis for); every other collection stays on JFJochReceiverFPGA. - Always: also the others, through JFJochReceiverLite (rc186's switch). - Never: everything on JFJochReceiverFPGA, its own live stills included (the rc188 behaviour, kept for comparison). Pedestal runs, summation on the host and runs without images never take it. Ported by hand, not cherry-picked: the puller files and its tests are restored from rc186-old; the service changed since (force_still, refine_solvent, ClearRugnuxStatus), so its dispatch is written anew around them. Tests: FPGAImagePullerTest (rc186's 20 cases on the mock, the switch as an enum, plus FPGAImagePuller_DefaultOnlyWithRugnuxLive); the three GPU-stills processing tests run on both the default and JFJochReceiverFPGA's live stills. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01UqXYdHHZ4cogS1mrGUtfN7 --- receiver/CMakeLists.txt | 1 + receiver/FPGAImagePuller.cpp | 312 ++++++++++ receiver/FPGAImagePuller.h | 95 +++ receiver/FrameTransformation.cpp | 11 +- receiver/FrameTransformation.h | 2 + receiver/JFJochReceiverService.cpp | 45 +- receiver/JFJochReceiverService.h | 12 + tests/CMakeLists.txt | 1 + tests/FPGAImagePullerTest.cpp | 815 +++++++++++++++++++++++++ tests/JFJochReceiverProcessingTest.cpp | 6 + 10 files changed, 1295 insertions(+), 5 deletions(-) create mode 100644 receiver/FPGAImagePuller.cpp create mode 100644 receiver/FPGAImagePuller.h create mode 100644 tests/FPGAImagePullerTest.cpp diff --git a/receiver/CMakeLists.txt b/receiver/CMakeLists.txt index dba0aa1cf..c49af596f 100644 --- a/receiver/CMakeLists.txt +++ b/receiver/CMakeLists.txt @@ -3,6 +3,7 @@ ADD_LIBRARY(JFJochReceiver STATIC FrameTransformation.cpp FrameTransformation.h + FPGAImagePuller.cpp FPGAImagePuller.h JFJochReceiverService.cpp JFJochReceiverService.h JFJochReceiverTest.cpp JFJochReceiverTest.h JFJochReceiverFPGA.cpp JFJochReceiverFPGA.h diff --git a/receiver/FPGAImagePuller.cpp b/receiver/FPGAImagePuller.cpp new file mode 100644 index 000000000..f8244c995 --- /dev/null +++ b/receiver/FPGAImagePuller.cpp @@ -0,0 +1,312 @@ +// SPDX-FileCopyrightText: 2026 Filip Leonarski, Paul Scherrer Institute +// SPDX-License-Identifier: GPL-3.0-only + +#include "FPGAImagePuller.h" + +#include +#include + + +FPGAImagePuller::FPGAImagePuller(const DiffractionExperiment &in_experiment, const PixelMask &mask, + const JFCalibration *calibration, AcquisitionDeviceGroup &in_devices, + Logger &in_logger, int64_t compression_threads, size_t in_max_slots) + : ImagePuller(in_max_slots + 2), // every slot, the start and the end message: Put never finds it full + experiment(in_experiment), + logger(in_logger), + devices(in_devices), + max_slots(in_max_slots), + image_dropped(experiment.GetImageNum(), 0) { + const int ndatastreams = experiment.GetDataStreamsNum(); + if (devices.size() < ndatastreams) + throw JFJochException(JFJochExceptionCategory::InputParameterInvalid, + "Number of acquisition devices has to match data streams"); + + for (int m = 0; m < experiment.GetModulesNum(); m++) + adu_histogram.emplace_back(std::make_unique()); + + for (int d = 0; d < ndatastreams; d++) { + devices[d].PrepareAction(experiment); + expected_packets_per_image += devices[d].Counters().GetExpectedPacketsPerImage(); + } + + if (experiment.GetDetectorType() != DetectorType::JUNGFRAU) + calibration = nullptr; + + // Making a slot is slow and its buffers are written once here: none is made, nor first touched, during the run + for (size_t i = 0; i < max_slots; i++) + free_slots.push_back(std::make_shared(experiment)); + + // The receiver's own start message is built from its experiment; this one only says the run has begun. + StartMessage start{}; + experiment.FillMessage(start); + outside_fifo.Put({.cbor = std::make_shared(start), + .received = std::chrono::steady_clock::now()}); + + for (int i = 0; i < compression_threads; i++) + compress_futures.emplace_back(std::async(std::launch::async, &FPGAImagePuller::CompressThread, this)); + + for (int d = 0; d < ndatastreams; d++) + for (int m = 0; m < experiment.GetModulesNum(d); m++) + module_futures.emplace_back(std::async(std::launch::async, &FPGAImagePuller::ModuleThread, this, d, m)); + + std::latch ready(ndatastreams); + for (int d = 0; d < ndatastreams; d++) + acquire_futures.emplace_back(std::async(std::launch::async, &FPGAImagePuller::AcquireThread, this, + static_cast(d), std::cref(mask), calibration, + std::ref(ready))); + ready.wait(); + + finish_future = std::async(std::launch::async, &FPGAImagePuller::FinalizeMeasurement, this); + + if (failed) { + try { + Stop(); + } catch (...) { + outside_fifo.Clear(); // the destructor does not run + throw; + } + } +} + +FPGAImagePuller::~FPGAImagePuller() { + try { + Stop(); + } catch (const std::exception &e) { + logger.Error("FPGA image puller teardown failed: {}", e.what()); + } + // These hold slots, which go back to this object + outside_fifo.Clear(); +} + +void FPGAImagePuller::SetError(std::exception_ptr e) { + std::unique_lock ul(error_mutex); + if (!error) + error = e; + failed = true; +} + +void FPGAImagePuller::Cancel() { + for (int d = 0; d < experiment.GetDataStreamsNum(); d++) + devices[d].Cancel(); +} + +void FPGAImagePuller::Stop() { + Cancel(); + std::call_once(finish_once, [this] { finish_future.get(); }); + std::unique_lock ul(error_mutex); + if (error) + std::rethrow_exception(std::exchange(error, nullptr)); +} + +void FPGAImagePuller::AcquireThread(uint16_t data_stream, const PixelMask &mask, const JFCalibration *calibration, + std::latch &ready) { + auto &device = devices[data_stream]; + try { + // Only what the card needs for the pixels: its analysis results are not read. + if (calibration != nullptr) + device.InitializeCalibration(experiment, *calibration); + device.InitializePixelMask(experiment, mask); + device.StartAction(experiment); + } catch (...) { + SetError(std::current_exception()); + Cancel(); // the module threads of the other cards have to come out as well + ready.count_down(); + return; + } + ready.count_down(); + + try { + device.WaitForActionComplete(); + } catch (...) { + SetError(std::current_exception()); + Cancel(); + } +} + +int64_t FPGAImagePuller::FastestFrame() const { + int64_t ret = 0; + for (int d = 0; d < experiment.GetDataStreamsNum(); d++) + ret = std::max(ret, static_cast(devices[d].Counters().GetFastestFrameNumber())); + return ret; +} + +// Polled: a dead card has to be noticed from the other cards' frames +void FPGAImagePuller::WaitForFrame(uint16_t data_stream, uint16_t module_number, int64_t frame) const { + const auto &counters = devices[data_stream].Counters(); + // A frame is complete once the module is two further on, as in JFJochReceiverFPGA + while ((static_cast(counters.GetCurrFrameNumber(module_number)) < frame + 2) + && !counters.IsAcquisitionFinished() && !failed + && (FastestFrame() < frame + 2 + MissingAfterFrames)) + std::this_thread::sleep_for(std::chrono::milliseconds(1)); +} + +// The last frame any card got; waits for all cards, so every module stops at the same image +int64_t FPGAImagePuller::LastFrame() const { + for (int d = 0; d < experiment.GetDataStreamsNum(); d++) + while (!devices[d].Counters().IsAcquisitionFinished() && !failed) + std::this_thread::sleep_for(std::chrono::milliseconds(1)); + return FastestFrame(); +} + +std::shared_ptr FPGAImagePuller::GetSlot(int64_t image_number) { + std::unique_lock ul(images_mutex); + if (image_dropped[image_number]) + return nullptr; + if (const auto it = images_in_progress.find(image_number); it != images_in_progress.end()) + return it->second; + + std::shared_ptr slot; + if (!free_slots.empty()) { + slot = free_slots.back(); + free_slots.pop_back(); + } else { + image_dropped[image_number] = 1; + dropped_images++; + Emit(image_number, std::nullopt); + return nullptr; + } + slot->image_number = image_number; + slot->metadata = std::make_unique(experiment); + slot->modules_left = static_cast(experiment.GetModulesNum()); + images_in_progress[image_number] = slot; + return slot; +} + +void FPGAImagePuller::ReturnSlot(const std::shared_ptr &slot) { + std::unique_lock ul(images_mutex); + free_slots.push_back(slot); +} + +void FPGAImagePuller::ModuleThread(uint16_t data_stream, uint16_t module_number) { + try { + auto &device = devices[data_stream]; + const auto &counters = device.Counters(); + const size_t module_abs = experiment.GetFirstModuleOfDataStream(data_stream) + module_number; + int64_t oldest_held = 0; + + for (int64_t image = 0; image < experiment.GetImageNum(); image++) { + WaitForFrame(data_stream, module_number, image); + + if (failed) + break; + + if (counters.IsAcquisitionFinished() + && (image > static_cast(counters.GetFastestFrameNumber())) + && (image > LastFrame())) + break; + + // A frame given up on can still arrive, late: its buffer goes back to the card. + while ((oldest_held < image) + && (oldest_held < static_cast(counters.GetCurrFrameNumber(module_number)))) + device.FrameBufferRelease(oldest_held++, module_number); + + const bool collected = counters.IsAnyPacketCollected(image, module_number); + if (const auto slot = GetSlot(image)) { + if (collected) { + const DeviceOutput *output = device.GetDeviceOutput(image, module_number); + slot->metadata->Process(output); + adu_histogram[module_abs]->Add(*output); + slot->transformation.ProcessModule(output, data_stream); + } else + slot->transformation.FillNotCollectedModule(module_number, data_stream); + + if (--slot->modules_left == 0) { + { + std::unique_lock ul(images_mutex); + images_in_progress.erase(image); + } + images_to_compress.Put(slot); + } + } + if (collected) + device.FrameBufferRelease(image, module_number); + } + } catch (...) { + SetError(std::current_exception()); + Cancel(); + } +} + +void FPGAImagePuller::CompressThread() { + while (const auto slot = images_to_compress.GetBlocking()) { + const int64_t image_number = slot->image_number; + try { + DataMessage message{}; + message.number = image_number; + message.original_number = image_number; + slot->metadata->Export(message, expected_packets_per_image); + // The card's spot finder and ROI map were not set up for this run; the receiver reports its own. + message.strong_pixel_count.reset(); + message.roi.clear(); + + if (message.image_collection_efficiency == 0.0f) { // no module of it came + ReturnSlot(slot); + Emit(image_number, std::nullopt); + continue; + } + + message.image = slot->transformation.GetCompressedImage(); + + ImagePullerOutput output; + output.cbor = std::make_shared(message); + // The image lives in the slot: it goes back when the last copy of this output is gone. + output.raw = std::shared_ptr( + new ReceiveBufferRegion{const_cast(message.image.GetCompressed()), + message.image.GetCompressedSize()}, + [this, slot](ReceiveBufferRegion *region) { + delete region; + ReturnSlot(slot); + }); + Emit(image_number, std::move(output)); + } catch (...) { + SetError(std::current_exception()); + Cancel(); + ReturnSlot(slot); + Emit(image_number, std::nullopt); + } + } +} + +// Whichever thread finishes the image next in line lets it, and those waiting behind it, out. +void FPGAImagePuller::Emit(int64_t image_number, std::optional output) { + std::unique_lock ul(order_mutex); + images_done.emplace(image_number, std::move(output)); + for (auto it = images_done.begin(); (it != images_done.end()) && (it->first == next_image); + it = images_done.erase(it), next_image++) { + if (it->second) { + it->second->received = std::chrono::steady_clock::now(); + outside_fifo.Put(std::move(*it->second)); + } + } +} + +void FPGAImagePuller::FinalizeMeasurement() { + for (auto &f: module_futures) + f.get(); + for (size_t i = 0; i < compress_futures.size(); i++) + images_to_compress.Put(nullptr); + for (auto &f: compress_futures) + f.get(); + + Cancel(); + for (auto &f: acquire_futures) + f.get(); + + // Only an error leaves images unfinished, holding back those behind them + { + std::unique_lock ul(order_mutex); + for (auto &[n, output]: images_done) + if (output) + outside_fifo.Put(std::move(*output)); + images_done.clear(); + } + + if (dropped_images > 0) + logger.Warning("FPGA image puller: {} images dropped, no free slot", dropped_images.load()); + + EndMessage end{}; + for (size_t i = 0; i < adu_histogram.size(); i++) + end.adu_histogram["module" + std::to_string(i)] = adu_histogram[i]->GetHistogram(); + outside_fifo.Put({.cbor = std::make_shared(end), + .received = std::chrono::steady_clock::now()}); +} diff --git a/receiver/FPGAImagePuller.h b/receiver/FPGAImagePuller.h new file mode 100644 index 000000000..e02f272d1 --- /dev/null +++ b/receiver/FPGAImagePuller.h @@ -0,0 +1,95 @@ +// SPDX-FileCopyrightText: 2026 Filip Leonarski, Paul Scherrer Institute +// SPDX-License-Identifier: GPL-3.0-only + +#pragma once + +#include +#include +#include +#include +#include +#include +#include +#include + +#include "FrameTransformation.h" +#include "ImageMetadata.h" +#include "../acquisition_device/AcquisitionDeviceGroup.h" +#include "../common/ADUHistogram.h" +#include "../image_puller/ImagePuller.h" +#include "../jungfrau/JFCalibration.h" + +// The images of a collection from the FPGA cards, as a detector stream: assembled and compressed here, in image order +class FPGAImagePuller : public ImagePuller { +public: + static constexpr size_t DefaultSlots = 128; + // A module this far behind the fastest one is taken as missing from that frame, as the device itself does + static constexpr int64_t MissingAfterFrames = AcquisitionCounters::ThresholdFramesLost + 2; +private: + struct Slot { + explicit Slot(const DiffractionExperiment &experiment) : transformation(experiment) { + transformation.ReserveCompressedBuffer(); + } + FrameTransformation transformation; + std::unique_ptr metadata; + std::atomic modules_left = 0; + int64_t image_number = 0; + }; + + const DiffractionExperiment experiment; + Logger &logger; + AcquisitionDeviceGroup &devices; + const size_t max_slots; + uint64_t expected_packets_per_image = 0; + + std::mutex images_mutex; + std::vector> free_slots; + std::map> images_in_progress; + std::vector image_dropped; + std::atomic dropped_images = 0; + + // What is done, waiting for the images before it. No value: that image will not come. + std::mutex order_mutex; + std::map> images_done; + int64_t next_image = 0; + + ThreadSafeFIFO> images_to_compress; + std::vector> adu_histogram; + + std::mutex error_mutex; + std::exception_ptr error; + std::atomic failed = false; // a failed card may never report finished: nothing waits for it then + void SetError(std::exception_ptr e); + + std::vector> acquire_futures; + std::vector> module_futures; + std::vector> compress_futures; + std::future finish_future; + std::once_flag finish_once; + + void AcquireThread(uint16_t data_stream, const PixelMask &mask, const JFCalibration *calibration, std::latch &ready); + void ModuleThread(uint16_t data_stream, uint16_t module_number); + void CompressThread(); + void FinalizeMeasurement(); + + void WaitForFrame(uint16_t data_stream, uint16_t module_number, int64_t frame) const; + int64_t FastestFrame() const; + int64_t LastFrame() const; + std::shared_ptr GetSlot(int64_t image_number); + void ReturnSlot(const std::shared_ptr &slot); + void Emit(int64_t image_number, std::optional output); +public: + // Arms the cards; when it returns the detector can be started. + FPGAImagePuller(const DiffractionExperiment &experiment, const PixelMask &mask, const JFCalibration *calibration, + AcquisitionDeviceGroup &devices, Logger &logger, int64_t compression_threads, + size_t max_slots = DefaultSlots); + ~FPGAImagePuller() override; + + void Disconnect() override {} + size_t GetDroppedImages() const override { return dropped_images; } + + // The collection is over, whatever the cards have got: what is on its way still comes, then the end message. + void Cancel(); + // After the receiver is done: stops the cards, waits for the threads, throws what went wrong with the cards. + void Stop(); +}; diff --git a/receiver/FrameTransformation.cpp b/receiver/FrameTransformation.cpp index 1f824217b..df5429ca5 100644 --- a/receiver/FrameTransformation.cpp +++ b/receiver/FrameTransformation.cpp @@ -59,6 +59,13 @@ size_t FrameTransformation::CompressImage(void *output, size_t output_size) { experiment.GetByteDepthImage()); } +void FrameTransformation::ReserveCompressedBuffer() { + if (experiment.GetCompressionAlgorithm() != CompressionAlgorithm::NO_COMPRESSION) + compressed_buffer.resize(MaxCompressedSize(experiment.GetCompressionAlgorithm(), + experiment.GetPixelsNum(), + experiment.GetByteDepthImage())); +} + CompressedImage FrameTransformation::GetCompressedImage() { const uint8_t *data; size_t size; @@ -66,9 +73,7 @@ CompressedImage FrameTransformation::GetCompressedImage() { data = reinterpret_cast(precompression_buffer.data()); size = experiment.GetPixelsNum() * experiment.GetByteDepthImage(); } else { - compressed_buffer.resize(MaxCompressedSize(experiment.GetCompressionAlgorithm(), - experiment.GetPixelsNum(), - experiment.GetByteDepthImage())); + ReserveCompressedBuffer(); data = reinterpret_cast(compressed_buffer.data()); size = CompressImage(compressed_buffer.data(), compressed_buffer.size()); } diff --git a/receiver/FrameTransformation.h b/receiver/FrameTransformation.h index 586a37adb..e8dc4e9ab 100644 --- a/receiver/FrameTransformation.h +++ b/receiver/FrameTransformation.h @@ -23,6 +23,8 @@ public: void ProcessModule(const DeviceOutput *output, int data_stream); void ProcessModule(const void *input, uint16_t module_number, int data_stream); void FillNotCollectedModule(uint16_t module_number, int data_stream); + // Allocates and writes the buffer GetCompressedImage() compresses into, so its pages are not first touched there + void ReserveCompressedBuffer(); CompressedImage GetCompressedImage(); // Throws CompressionBufferTooSmallException if the image does not fit output_size. size_t CompressImage(void *output, size_t output_size); diff --git a/receiver/JFJochReceiverService.cpp b/receiver/JFJochReceiverService.cpp index 5e101ace8..724e65e15 100644 --- a/receiver/JFJochReceiverService.cpp +++ b/receiver/JFJochReceiverService.cpp @@ -38,6 +38,31 @@ JFJochReceiverService &JFJochReceiverService::RugnuxLive(bool enable, std::share return *this; } +JFJochReceiverService &JFJochReceiverService::UseFPGAImagePuller(FPGAImagePullerUse use, size_t slots) { + std::unique_lock ul_state(state_mutex); + if (state != ReceiverState::Idle) + throw JFJochException(JFJochExceptionCategory::WrongDAQState, + "Cannot change the receiver path during data collection"); + fpga_image_puller = use; + fpga_image_puller_slots = slots; + return *this; +} + +// Pedestal runs and summation on the host need JFJochReceiverFPGA +bool JFJochReceiverService::FPGAImagePullerFor(const DiffractionExperiment &experiment) const { + if ((experiment.GetDetectorType() == DetectorType::DECTRIS) || experiment.IsPedestalRun() + || experiment.IsCPUSummation() || (experiment.GetImageNum() <= 0)) + return false; + switch (fpga_image_puller) { + case FPGAImagePullerUse::Always: + return true; + case FPGAImagePullerUse::RugnuxLive: + return rugnux_enable && (experiment.GetDetectorMode() == DetectorMode::Standard); + default: + return false; + } +} + RugnuxLiveSnapshot JFJochReceiverService::GetRugnuxStatus() const { return rugnux_status.Get(); } @@ -66,6 +91,8 @@ void JFJochReceiverService::FinalizeMeasurementChangeState() { void JFJochReceiverService::FinalizeMeasurement() { try { receiver->StopReceiver(); + if (fpga_puller) + fpga_puller->Stop(); } catch (...) { FinalizeMeasurementChangeState(); throw; @@ -106,11 +133,20 @@ void JFJochReceiverService::Start(const DiffractionExperiment &experiment, try { // First clean-up old measurement receiver.reset(); + image_puller.reset(); + fpga_puller.reset(); analysis_warning.clear(); preview_image.Configure(experiment, pixel_mask); - if (experiment.GetDetectorType() != DetectorType::DECTRIS) { + // A PSI detector's frames through FPGAImagePuller go to the stream receivers, as a DECTRIS stream does + if (FPGAImagePullerFor(experiment)) { + fpga_puller = std::make_shared(experiment, pixel_mask, calibration, aq_devices, logger, + nthreads, fpga_image_puller_slots); + puller = fpga_puller; + } + + if ((experiment.GetDetectorType() != DetectorType::DECTRIS) && !fpga_puller) { // Summation on the host runs threads of its own for each image auto fpga_nthreads = nthreads; if (experiment.IsCPUSummation()) @@ -195,6 +231,8 @@ void JFJochReceiverService::Start(const DiffractionExperiment &experiment, state = ReceiverState::Running; } catch (const std::exception &e) { receiver.reset(); // its threads may be polling the puller + image_puller.reset(); + fpga_puller.reset(); // The receiver never started, so drop the status its base constructor had already reset - // otherwise /status and /statistics keep reporting a zero-progress run that never happened, // until the next start overwrites it. @@ -207,8 +245,11 @@ void JFJochReceiverService::Start(const DiffractionExperiment &experiment, void JFJochReceiverService::Cancel(bool silent) { std::unique_lock ul(state_mutex); - if (state == ReceiverState::Running) + if (state == ReceiverState::Running) { receiver->Cancel(silent); + if (fpga_puller) + fpga_puller->Cancel(); + } } JFJochReceiverOutput JFJochReceiverService::Stop() { diff --git a/receiver/JFJochReceiverService.h b/receiver/JFJochReceiverService.h index 26ca10a26..d11d2c818 100644 --- a/receiver/JFJochReceiverService.h +++ b/receiver/JFJochReceiverService.h @@ -9,6 +9,7 @@ #include #include "JFJochReceiver.h" +#include "FPGAImagePuller.h" #include "../preview/PreviewImage.h" #include "../image_puller/ZMQImagePuller.h" #include "../image_analysis/indexing/IndexerThreadPool.h" @@ -19,6 +20,10 @@ struct RugnuxModel; +// RugnuxLive: collections analysed by rugnux live; Always: also the others, through JFJochReceiverLite; +// Never: all on JFJochReceiverFPGA, its own live stills included +enum class FPGAImagePullerUse { RugnuxLive, Always, Never }; + class JFJochReceiverService { std::unique_ptr receiver; AcquisitionDeviceGroup &aq_devices; @@ -38,6 +43,12 @@ class JFJochReceiverService { RugnuxLiveStatus rugnux_status; // of the last collection, kept after it ends std::string analysis_warning; // why the collection was not analysed as asked, for the broker's status + // Which PSI collections go through FPGAImagePuller and the stream receivers + FPGAImagePullerUse fpga_image_puller = FPGAImagePullerUse::RugnuxLive; + size_t fpga_image_puller_slots = FPGAImagePuller::DefaultSlots; + std::shared_ptr fpga_puller; + bool FPGAImagePullerFor(const DiffractionExperiment &experiment) const; + enum class ReceiverState {Idle, Running}; ReceiverState state = ReceiverState::Idle; mutable std::mutex state_mutex; @@ -64,6 +75,7 @@ public: double deadline_s, bool refine_solvent = false, bool force_still = false); RugnuxLiveSnapshot GetRugnuxStatus() const; void ClearRugnuxStatus(); // back to Idle, as before any collection + JFJochReceiverService& UseFPGAImagePuller(FPGAImagePullerUse use, size_t slots = FPGAImagePuller::DefaultSlots); JFJochReceiverService& PreviewSocket(const std::string &addr, const std::optional &watermark = {}); JFJochReceiverService& MetadataSocket(const std::string &addr); diff --git a/tests/CMakeLists.txt b/tests/CMakeLists.txt index 8684e8e73..f30cb28c6 100644 --- a/tests/CMakeLists.txt +++ b/tests/CMakeLists.txt @@ -155,6 +155,7 @@ ADD_EXECUTABLE(jfjoch_test ImageMetadataTest.cpp JFJochReceiverLiteTest.cpp JFJochReceiverRugnuxTest.cpp + FPGAImagePullerTest.cpp GridScanSettingsTest.cpp JFJochReceiverPlotsTest.cpp GoniometerAxisTest.cpp diff --git a/tests/FPGAImagePullerTest.cpp b/tests/FPGAImagePullerTest.cpp new file mode 100644 index 000000000..f7bf6b89a --- /dev/null +++ b/tests/FPGAImagePullerTest.cpp @@ -0,0 +1,815 @@ +// SPDX-FileCopyrightText: 2026 Filip Leonarski, Paul Scherrer Institute +// SPDX-License-Identifier: GPL-3.0-only + +// The same frames through JFJochReceiverFPGA and through FPGAImagePuller + JFJochReceiverLite, on the mock of the +// card. The pixels must be the same; the analysis differs by design, and its numbers are printed. + +#include + +#include +#include +#include +#include +#include +#include + +#include "../compression/JFJochDecompress.h" +#include "../frame_serialize/CBORStream2Deserializer.h" +#include "../image_pusher/HDF5FilePusher.h" +#include "../image_pusher/ImagePusher.h" +#include "../writer/HDF5Objects.h" +#include "../writer/StreamWriter.h" +#include "../receiver/FPGAImagePuller.h" +#include "../receiver/JFJochReceiverRugnuxRotation.h" +#include "../receiver/JFJochReceiverService.h" +#include "../rugnux/RugnuxDefaults.h" +#include "MockCardOutput.h" + +using namespace std::chrono_literals; + +namespace { + struct Received { + DataMessage message; + std::vector compressed; + }; + + class CollectingPusher : public ImagePusher { + public: + std::mutex m; + std::map images; + std::vector arrival; + std::vector sequence; + EndMessage end; + std::chrono::milliseconds delay{0}; + + void StartDataCollection(StartMessage &) override { + std::unique_lock ul(m); + sequence.emplace_back("start"); + } + bool EndDataCollection(const EndMessage &message) override { + std::unique_lock ul(m); + sequence.emplace_back("end"); + end = message; + return true; + } + bool SendCalibration(const CompressedImage &c) override { + std::unique_lock ul(m); + sequence.emplace_back("calibration " + c.GetChannel()); + return true; + } + bool SendImage(const uint8_t *image_data, size_t image_size, int64_t image_number) override { + std::this_thread::sleep_for(delay); + auto d = CBORStream2Deserialize(image_data, image_size); + Received r; + r.message = d->data_message.value(); + const uint8_t *p = r.message.image.GetCompressed(); + r.compressed.assign(p, p + r.message.image.GetCompressedSize()); + r.message.image = CompressedImage(r.compressed.data(), r.compressed.size(), r.message.image.GetWidth(), + r.message.image.GetHeight(), r.message.image.GetMode(), + r.message.image.GetCompressionAlgorithm()); + std::unique_lock ul(m); + sequence.emplace_back("image"); + arrival.push_back(image_number); + images.emplace(image_number, std::move(r)); + return true; + } + std::string PrintSetup() const override { return "collecting"; } + ImagePusherType GetType() const override { return ImagePusherType::Test; } + }; + + float Pedestal(int module, int pixel) { + return 3000 + 10 * module + pixel % 50; + } + + JFCalibration Calibration(const DiffractionExperiment &x) { + JFCalibration ret(x); + std::vector g0(RAW_MODULE_SIZE), g1(RAW_MODULE_SIZE), g2(RAW_MODULE_SIZE); + for (int s = 0; s < x.GetStorageCellNumber(); s++) + for (int m = 0; m < x.GetModulesNum(); m++) { + for (int i = 0; i < RAW_MODULE_SIZE; i++) { + g0[i] = Pedestal(m, i); + g1[i] = 15000 + 10 * m + i % 50; + g2[i] = 14000 + 10 * m + i % 50; + } + ret.Pedestal(m, 0, s).LoadPedestal(g0); + ret.Pedestal(m, 1, s).LoadPedestal(g1); + ret.Pedestal(m, 2, s).LoadPedestal(g2); + } + return ret; + } + + // Raw detector frame of a module: background of a few photons, some spots, one saturated and one bad + // pixel, different for each frame. + std::vector Frame(int64_t frame, int module, bool jungfrau) { + std::vector ret(RAW_MODULE_SIZE); + std::mt19937 g(static_cast(frame * 100 + module)); + std::uniform_int_distribution background(0, jungfrau ? 300 : 3); + for (int i = 0; i < RAW_MODULE_SIZE; i++) + ret[i] = (jungfrau ? static_cast(Pedestal(module, i)) : 0) + background(g); + + std::uniform_int_distribution where_x(20, RAW_MODULE_COLS - 20), where_y(20, RAW_MODULE_LINES - 20); + for (int s = 0; s < 40; s++) { + const int x0 = where_x(g), y0 = where_y(g); + for (int y = y0; y < y0 + 3; y++) + for (int x = x0; x < x0 + 3; x++) + ret[y * RAW_MODULE_COLS + x] = jungfrau ? 12000 : 2000; + } + ret[50 * RAW_MODULE_COLS + 500] = jungfrau ? 0xC000 : 0xFFFE; + ret[60 * RAW_MODULE_COLS + 600] = 0xFFFF; + return ret; + } + + SpotFindingSettings Spots() { + SpotFindingSettings s = DiffractionExperiment::DefaultDataProcessingSettings(); + s.signal_to_noise_threshold = 3; + s.photon_count_threshold = 2; + s.min_pix_per_spot = 1; + s.indexing = false; + return s; + } + + // What the card writes for the first frames: their conversion + std::vector CardImages(const DiffractionExperiment &x, int64_t distinct_frames) { + const bool jungfrau = x.GetDetectorType() == DetectorType::JUNGFRAU; + PixelMask mask(x); + const JFCalibration calib = Calibration(x); + std::vector ret; + for (int64_t f = 0; f < distinct_frames; f++) { + std::vector raw; + for (int m = 0; m < x.GetModulesNum(); m++) { + const auto frame = Frame(f, m, jungfrau); + raw.insert(raw.end(), frame.begin(), frame.end()); + } + ret.push_back(ConvertedImage(x, calib, mask, raw)); + } + return ret; + } + + // The card writing zeros + AcquisitionDeviceGroup Devices(const DiffractionExperiment &x) { + return MockDevices(x, {}); + } + + struct PathResult { + std::map images; + std::vector arrival; + std::vector sequence; + EndMessage end; + JFJochReceiverOutput output; + }; + + PathResult Run(const DiffractionExperiment &x, bool puller, int64_t distinct_frames, bool rugnux = false) { + auto devices = MockDevices(x, CardImages(x, distinct_frames)); + Logger logger("FPGAImagePullerTest"); + CollectingPusher pusher; + JFJochReceiverService service(devices, logger, pusher, 256); + service.NumThreads(4); + service.SetSpotFindingSettings(Spots()); + service.UseFPGAImagePuller(puller ? FPGAImagePullerUse::Always : FPGAImagePullerUse::Never); + service.RugnuxLive(rugnux, nullptr, 2, 30); + + PixelMask mask(x); + const JFCalibration calib = Calibration(x); + service.Start(x, mask, &calib); + PathResult ret; + ret.output = service.Stop(); + ret.images = std::move(pusher.images); + ret.arrival = std::move(pusher.arrival); + ret.sequence = std::move(pusher.sequence); + ret.end = pusher.end; + return ret; + } + + std::vector Pixels(const CompressedImage &image) { + std::vector ret; + image.GetUncompressed(ret); + return ret; + } + + template + void Row(const std::string &name, const std::optional &a, const std::optional &b) { + if (a == b) + return; + std::cout << " differs " << name << ": FPGA "; + if (a) std::cout << *a; else std::cout << "-"; + std::cout << " puller "; + if (b) std::cout << *b; else std::cout << "-"; + std::cout << std::endl; + } + + // Must be the same: asserted. Analysis: printed for the first image and summed over all. + void Compare(const std::string &name, const PathResult &a, const PathResult &b) { + std::cout << "=== " << name << std::endl; + REQUIRE(a.images.size() == b.images.size()); + REQUIRE(!a.images.empty()); + + int64_t spots_a = 0, spots_b = 0, sat_a = 0, sat_b = 0, err_a = 0, err_b = 0, strong_a = 0, strong_b = 0; + double dot = 0, norm_a = 0, norm_b = 0, ratio_sum = 0; + size_t ratio_n = 0, bins_a = 0, bins_b = 0; + + for (const auto &[n, ia]: a.images) { + INFO("image " << n); + REQUIRE(b.images.contains(n)); + const auto &ib = b.images.at(n); + const auto &ma = ia.message; + const auto &mb = ib.message; + + CHECK(ma.image.GetMode() == mb.image.GetMode()); + CHECK(ma.image.GetCompressionAlgorithm() == mb.image.GetCompressionAlgorithm()); + CHECK(ma.image.GetWidth() == mb.image.GetWidth()); + CHECK(ma.image.GetHeight() == mb.image.GetHeight()); + CHECK(Pixels(ma.image) == Pixels(mb.image)); + CHECK(ia.compressed.size() == ib.compressed.size()); + + // From the source + CHECK(ma.number == mb.number); + CHECK(ma.original_number == mb.original_number); + CHECK(ma.packets_expected == mb.packets_expected); + CHECK(ma.packets_received == mb.packets_received); + CHECK(ma.image_collection_efficiency == mb.image_collection_efficiency); + CHECK(ma.timestamp == mb.timestamp); + CHECK(ma.timestamp_base == mb.timestamp_base); + CHECK(ma.exptime == mb.exptime); + CHECK(ma.exptime_base == mb.exptime_base); + CHECK(ma.jf_info == mb.jf_info); + CHECK(ma.storage_cell == mb.storage_cell); + CHECK(ma.xfel_pulse_id == mb.xfel_pulse_id); + CHECK(ma.xfel_event_code == mb.xfel_event_code); + CHECK(ma.pixel_sum == mb.pixel_sum); + CHECK(ma.user_data == mb.user_data); + CHECK(ma.run_number == mb.run_number); + CHECK(ma.run_name == mb.run_name); + + if (n == a.images.begin()->first) { + Row("saturated_pixel_count", ma.saturated_pixel_count, mb.saturated_pixel_count); + Row("error_pixel_count", ma.error_pixel_count, mb.error_pixel_count); + Row("min_viable_pixel_value", ma.min_viable_pixel_value, mb.min_viable_pixel_value); + Row("max_viable_pixel_value", ma.max_viable_pixel_value, mb.max_viable_pixel_value); + Row("strong_pixel_count", ma.strong_pixel_count, mb.strong_pixel_count); + Row("spot_count", ma.spot_count, mb.spot_count); + Row("bkg_estimate", ma.bkg_estimate, mb.bkg_estimate); + Row("ice_ring_score", ma.ice_ring_score, mb.ice_ring_score); + Row("receiver_aq_dev_delay", ma.receiver_aq_dev_delay, mb.receiver_aq_dev_delay); + Row("receiver_buf_in_preparation", ma.receiver_buf_in_preparation, mb.receiver_buf_in_preparation); + Row("receiver_buf_in_sending", ma.receiver_buf_in_sending, mb.receiver_buf_in_sending); + std::cout << " compression_ratio FPGA " << ma.compression_ratio.value_or(0) + << " puller " << mb.compression_ratio.value_or(0) << std::endl; + } + spots_a += ma.spots.size(); + spots_b += mb.spots.size(); + sat_a += ma.saturated_pixel_count.value_or(0); + sat_b += mb.saturated_pixel_count.value_or(0); + err_a += ma.error_pixel_count.value_or(0); + err_b += mb.error_pixel_count.value_or(0); + strong_a += ma.strong_pixel_count.value_or(0); + strong_b += mb.strong_pixel_count.value_or(0); + + bins_a = ma.az_int_profile.size(); + bins_b = mb.az_int_profile.size(); + for (size_t i = 0; i < std::min(bins_a, bins_b); i++) { + if (std::isfinite(ma.az_int_profile[i]) && std::isfinite(mb.az_int_profile[i])) { + dot += ma.az_int_profile[i] * mb.az_int_profile[i]; + norm_a += ma.az_int_profile[i] * ma.az_int_profile[i]; + norm_b += mb.az_int_profile[i] * mb.az_int_profile[i]; + if (ma.az_int_profile[i] != 0) { + ratio_sum += mb.az_int_profile[i] / ma.az_int_profile[i]; + ratio_n++; + } + } + } + } + std::cout << " over " << a.images.size() << " images:" + << " spots FPGA " << spots_a << " puller " << spots_b + << " | strong " << strong_a << " / " << strong_b + << " | saturated " << sat_a << " / " << sat_b + << " | error " << err_a << " / " << err_b + << " | az bins " << bins_a << " / " << bins_b + << " cosine " << (norm_a * norm_b > 0 ? dot / std::sqrt(norm_a * norm_b) : 0) + << " mean ratio puller/FPGA " << (ratio_n > 0 ? ratio_sum / ratio_n : 0) << std::endl; + + const auto &sa = a.output.status; + const auto &sb = b.output.status; + std::cout << " status: efficiency " << a.output.efficiency << " / " << b.output.efficiency + << " | collected " << sa.images_collected << " / " << sb.images_collected + << " | sent " << sa.images_sent << " / " << sb.images_sent + << " | dropped " << sa.images_dropped << " / " << sb.images_dropped + << " | max_image_sent " << sa.max_image_number_sent << " / " << sb.max_image_number_sent + << " | compressed_size " << sa.compressed_size << " / " << sb.compressed_size + << " | ratio " << sa.compressed_ratio.value_or(0) << " / " << sb.compressed_ratio.value_or(0) + << " | max_delay " << sa.max_receive_delay.value_or(0) << " / " << sb.max_receive_delay.value_or(0) + << std::endl; + + CHECK(a.output.efficiency == b.output.efficiency); + CHECK(sa.images_collected == sb.images_collected); + CHECK(sa.images_sent == sb.images_sent); + CHECK(sb.images_dropped == 0); + CHECK(sa.max_image_number_sent == sb.max_image_number_sent); + CHECK(sa.compressed_size == sb.compressed_size); + CHECK(a.end.images_collected_count == b.end.images_collected_count); + CHECK(a.end.images_sent_to_write_count == b.end.images_sent_to_write_count); + CHECK(a.end.max_image_number == b.end.max_image_number); + CHECK(a.end.adu_histogram == b.end.adu_histogram); + + // Calibration goes to the writer only from the FPGA receiver + CHECK(a.sequence.front() == "start"); + CHECK(b.sequence.front() == "start"); + CHECK(a.sequence.back() == "end"); + CHECK(b.sequence.back() == "end"); + auto sequence_a = a.sequence; + std::erase_if(sequence_a, [](const std::string &s) { return s.starts_with("calibration"); }); + CHECK(sequence_a == b.sequence); + + int64_t displacement = 0; + for (size_t i = 0; i < b.arrival.size(); i++) + displacement = std::max(displacement, std::abs(b.arrival[i] - static_cast(i))); + std::cout << " max displacement at the pusher (Lite's threads): " << displacement << " images" << std::endl; + } + + void CompareBoth(const std::string &name, const DiffractionExperiment &x, int64_t distinct_frames) { + Compare(name, Run(x, false, distinct_frames), Run(x, true, distinct_frames)); + } + + DiffractionExperiment Base(const DetectorSetup &detector, int64_t images, int64_t distinct_frames) { + DiffractionExperiment x(detector); + x.PedestalG0Frames(0).NumTriggers(1).UseInternalPacketGenerator(true).InternalPacketGeneratorImages(distinct_frames) + .ImagesPerTrigger(images).ImagesPerFile(10).IncidentEnergy_keV(12.4) + .DetectorDistance_mm(75).BeamX_pxl(500).BeamY_pxl(600); + return x; + } +} + +TEST_CASE("FPGAImagePuller_SameAsFPGA_JF_Conversion", "[FPGAImagePuller]") { + auto x = Base(DetJF(2), 6, 3); + x.Conversion(); + x.Compression(CompressionAlgorithm::BSHUF_LZ4); + CompareBoth("JF conversion, int16, BSHUF_LZ4", x, 3); +} + +TEST_CASE("FPGAImagePuller_SameAsFPGA_JF_Conversion_ApplyMask_ROI", "[FPGAImagePuller]") { + auto x = Base(DetJF(2), 4, 2); + x.Conversion(); + x.Compression(CompressionAlgorithm::BSHUF_ZSTD).ApplyPixelMask(true); + x.ROI().SetROI(ROIDefinition{.boxes = {ROIBox("box", 380, 450, 280, 320)}, .circles = {}, .azimuthal = {}}); + const auto a = Run(x, false, 2); + const auto b = Run(x, true, 2); + Compare("JF conversion, applied mask, ROI, BSHUF_ZSTD", a, b); + const auto &ra = a.images.begin()->second.message.roi.at("box"); + const auto &rb = b.images.begin()->second.message.roi.at("box"); + std::cout << " ROI sum " << ra.sum << " / " << rb.sum << " pixels " << ra.pixels << " / " << rb.pixels + << " max " << ra.max_count << " / " << rb.max_count << std::endl; +} + +TEST_CASE("FPGAImagePuller_SameAsFPGA_JF_Conversion_Unsigned", "[FPGAImagePuller]") { + auto x = Base(DetJF(2), 4, 2); + x.Conversion(); + x.Compression(CompressionAlgorithm::BSHUF_LZ4).BitDepthImage(16).PixelSigned(false); + CompareBoth("JF conversion, uint16, BSHUF_LZ4", x, 2); +} + +TEST_CASE("FPGAImagePuller_SameAsFPGA_JF_Conversion_Summation", "[FPGAImagePuller]") { + auto x = Base(DetJF(1), 3, 2); + x.Conversion(); + x.Summation(2).Compression(CompressionAlgorithm::BSHUF_LZ4); + CompareBoth("JF conversion, card sums 2 frames, int32", x, 2); +} + +TEST_CASE("FPGAImagePuller_SameAsFPGA_JF_Conversion_NoGeometry", "[FPGAImagePuller]") { + auto x = Base(DetJF(2), 4, 2); + x.Conversion(); + x.GeometryTransformation(false).Compression(CompressionAlgorithm::BSHUF_LZ4); + CompareBoth("JF conversion, no geometry transform", x, 2); +} + +TEST_CASE("FPGAImagePuller_SameAsFPGA_JF_Raw", "[FPGAImagePuller]") { + auto x = Base(DetJF(2), 4, 2); + x.Raw(); + x.Compression(CompressionAlgorithm::BSHUF_LZ4); + CompareBoth("JF raw, BSHUF_LZ4", x, 2); +} + +TEST_CASE("FPGAImagePuller_SameAsFPGA_JF_Raw_NoCompression", "[FPGAImagePuller]") { + auto x = Base(DetJF(1), 3, 1); + x.Raw(); + x.Compression(CompressionAlgorithm::NO_COMPRESSION); + CompareBoth("JF raw, no compression", x, 1); +} + +TEST_CASE("FPGAImagePuller_SameAsFPGA_EIGER_Conversion", "[FPGAImagePuller]") { + auto x = Base(DetEIGER(2), 4, 2); + x.Conversion(); + x.Compression(CompressionAlgorithm::BSHUF_LZ4); + CompareBoth("EIGER assembled, 16 bit, BSHUF_LZ4", x, 2); +} + +TEST_CASE("FPGAImagePuller_SameAsFPGA_EIGER_Raw", "[FPGAImagePuller]") { + auto x = Base(DetEIGER(2), 4, 2); + x.Raw(); + x.Compression(CompressionAlgorithm::BSHUF_ZSTD); + CompareBoth("EIGER raw layout, 16 bit, BSHUF_ZSTD", x, 2); +} + +TEST_CASE("FPGAImagePuller_SameAsFPGA_EIGER_32bit", "[FPGAImagePuller]") { + auto x = Base(DetEIGER(2), 3, 1); + x.Compression(CompressionAlgorithm::BSHUF_LZ4); + x.EigerBitDepth(32); + // The 16-bit raw frames do not map onto a 32-bit stream: the card writes zeros + auto devices = Devices(x); + Logger logger("FPGAImagePuller_EIGER32"); + for (const bool puller: {false, true}) { + CollectingPusher pusher; + JFJochReceiverService service(devices, logger, pusher, 256); + service.NumThreads(4).SetSpotFindingSettings(Spots()); + service.UseFPGAImagePuller(puller ? FPGAImagePullerUse::Always : FPGAImagePullerUse::Never); + PixelMask mask(x); + service.Start(x, mask, nullptr); + const auto out = service.Stop(); + CHECK(out.efficiency == 1.0f); + CHECK(pusher.images.size() == 3); + CHECK(pusher.images.at(0).message.image.GetMode() == x.GetImageMode()); + } +} + +// Nobody takes the images: the slots run out and later images are dropped whole, without any waiting. +TEST_CASE("FPGAImagePuller_SlowConsumer_Puller", "[FPGAImagePuller]") { + auto x = Base(DetJF(1), 20, 1); + x.Conversion(); + x.Compression(CompressionAlgorithm::BSHUF_LZ4); + + auto devices = Devices(x); + Logger logger("FPGAImagePuller_SlowConsumer"); + PixelMask mask(x); + const JFCalibration calib = Calibration(x); + FPGAImagePuller puller(x, mask, &calib, devices, logger, 2, 4); + + // Not read until the card is through, however long the simulation takes + while (!devices[0].Counters().IsAcquisitionFinished()) + std::this_thread::sleep_for(10ms); + + std::vector numbers; + bool end = false; + const auto t0 = std::chrono::steady_clock::now(); + while (!end && std::chrono::steady_clock::now() - t0 < 60s) { + const auto m = puller.PollImage(10ms); + if (!m) + continue; + if (m->cbor->data_message) + numbers.push_back(m->cbor->data_message->number); + end = m->cbor->end_message.has_value(); + } + CHECK(end); + puller.Stop(); + std::cout << "slow consumer, puller alone: " << numbers.size() << " images, " + << puller.GetDroppedImages() << " dropped" << std::endl; + CHECK(numbers.size() + puller.GetDroppedImages() == 20); + CHECK(puller.GetDroppedImages() > 0); + for (size_t i = 1; i < numbers.size(); i++) + CHECK(numbers[i] > numbers[i - 1]); +} + +// The same behind Lite: a writer that takes its time keeps Lite's only thread, and the drops reach the statistics. +TEST_CASE("FPGAImagePuller_SlowConsumer_Receiver", "[FPGAImagePuller]") { + auto x = Base(DetJF(1), 24, 1); + x.Conversion(); + x.Compression(CompressionAlgorithm::BSHUF_LZ4); + + auto devices = Devices(x); + Logger logger("FPGAImagePuller_SlowReceiver"); + CollectingPusher pusher; + pusher.delay = 3s; + JFJochReceiverService service(devices, logger, pusher, 256); + service.NumThreads(1).SetSpotFindingSettings(Spots()); + service.UseFPGAImagePuller(FPGAImagePullerUse::Always, 2); + + PixelMask mask(x); + const JFCalibration calib = Calibration(x); + service.Start(x, mask, &calib); + const auto out = service.Stop(); + + std::cout << "slow consumer, Lite: collected " << out.status.images_collected << " dropped " + << out.status.images_dropped << " efficiency " << out.efficiency << std::endl; + CHECK(out.status.images_dropped > 0); + CHECK(out.status.images_collected + out.status.images_dropped == 24); + CHECK(out.efficiency == Catch::Approx(static_cast(out.status.images_collected) / 24.0f)); + CHECK(pusher.sequence.back() == "end"); +} + +// A module frame missing in the middle, and a module that dies: the images keep coming with no help +// from the end of the run, and the missing module is filled, as in JFJochReceiverFPGA. +TEST_CASE("FPGAImagePuller_MissingModule", "[FPGAImagePuller]") { + constexpr int64_t images = 62; + constexpr int64_t dies_at = 3; + auto x = Base(DetJF(2), images, 1); + x.UseInternalPacketGenerator(false).Conversion(); + x.Compression(CompressionAlgorithm::BSHUF_LZ4); + + auto device = std::make_unique(0, 64); + SetOutputs(*device, x, 0, CardImages(x, 1)); + for (int64_t f = 0; f < images; f++) + for (int m = 0; m < 2; m++) { + if ((m == 1) && (f == 1 || f >= dies_at)) + continue; + device->CreateJFPackets(x, f + 1, 1, m, nullptr); + } + AcquisitionDeviceGroup devices; + devices.Add(std::move(device)); + + Logger logger("FPGAImagePuller_MissingModule"); + PixelMask mask(x); + const JFCalibration calib = Calibration(x); + FPGAImagePuller puller(x, mask, &calib, devices, logger, 2); + + // No final packet and no cancel yet: images must come through anyway, up to the lag behind the card + std::vector numbers; + std::vector efficiency; + bool stop_requested = false, end = false; + size_t images_before_cancel = 0; + const auto t0 = std::chrono::steady_clock::now(); + auto last = t0; + while (!end && std::chrono::steady_clock::now() - t0 < 900s) { + const auto m = puller.PollImage(10ms); + if (!m) { + if (!stop_requested && std::chrono::steady_clock::now() - last > 5s) { + stop_requested = true; + std::cout << "dead module, before cancel: fastest " << devices[0].Counters().GetFastestFrameNumber() + << " module 0 at " << devices[0].Counters().GetCurrFrameNumber(0) + << " module 1 at " << devices[0].Counters().GetCurrFrameNumber(1) + << " images so far " << numbers.size() << std::endl; + puller.Cancel(); + } + continue; + } + last = std::chrono::steady_clock::now(); + if (m->cbor->data_message) { + const auto &d = *m->cbor->data_message; + numbers.push_back(d.number); + efficiency.push_back(d.image_collection_efficiency.value_or(-1)); + if (!stop_requested) + images_before_cancel = numbers.size(); + + if (d.number == 1) { + // Module 1 absent from this frame: its pixels are the fill value + std::vector tmp; + const auto *p = reinterpret_cast(d.image.GetUncompressedPtr(tmp)); + CHECK(p[x.GetPixel0OfModuleConv(1)] == x.GetImageFillValue()); + CHECK(p[x.GetPixel0OfModuleConv(0)] != x.GetImageFillValue()); + } + } + end = m->cbor->end_message.has_value(); + } + CHECK(end); + REQUIRE_NOTHROW(puller.Stop()); + std::cout << "dead module: " << numbers.size() << " images, before any cancel: " + << images_before_cancel << std::endl; + // Image i is let go once the card reports frame i + 2 + MissingAfterFrames of the other module + CHECK(images_before_cancel >= 4); + REQUIRE(numbers.size() >= 4); + for (size_t i = 0; i < numbers.size(); i++) + CHECK(numbers[i] == static_cast(i)); + CHECK(efficiency[0] == 1.0f); + CHECK(efficiency[1] == 0.5f); + // Frame 2 of module 1 is sent, but the card holds a module's last frames until newer ones push them + // out: given up on, it comes with the cancel. Its buffer went back. + CHECK(efficiency[3] == 0.5f); + CHECK(efficiency.back() == 0.5f); +} + +TEST_CASE("FPGAImagePuller_Cancel", "[FPGAImagePuller]") { + for (const bool silent: {false, true}) { + auto x = Base(DetJF(2), 6, 1); + x.UseInternalPacketGenerator(false).Conversion(); + x.Compression(CompressionAlgorithm::BSHUF_LZ4); + + auto device = std::make_unique(0, 64); + SetOutputs(*device, x, 0, CardImages(x, 3)); + for (int64_t f = 0; f < 3; f++) + for (int m = 0; m < 2; m++) + device->CreateJFPackets(x, f + 1, 1, m, nullptr); + AcquisitionDeviceGroup devices; + devices.Add(std::move(device)); + + Logger logger("FPGAImagePuller_Cancel"); + CollectingPusher pusher; + JFJochReceiverService service(devices, logger, pusher, 256); + service.NumThreads(2).SetSpotFindingSettings(Spots()); + service.UseFPGAImagePuller(FPGAImagePullerUse::Always); + PixelMask mask(x); + const JFCalibration calib = Calibration(x); + service.Start(x, mask, &calib); + + std::this_thread::sleep_for(2s); + service.Cancel(silent); + const auto out = service.Stop(); + + std::cout << "cancel silent=" << silent << ": cancelled " << out.status.cancelled << " collected " + << out.status.images_collected << " sent " << out.status.images_sent << " efficiency " + << out.efficiency << std::endl; + CHECK(out.status.cancelled == !silent); + CHECK(pusher.sequence.front() == "start"); + CHECK(pusher.sequence.back() == "end"); + CHECK(out.status.images_collected <= 3); + if (silent) { + CHECK(out.status.images_collected == 3); + CHECK(out.efficiency == Catch::Approx(0.5f)); + } + } +} + +// Summation above the card's limit never takes the puller +TEST_CASE("FPGAImagePuller_NotForPedestalAndHostSummation", "[FPGAImagePuller]") { + auto x = Base(DetJF(1), 2, 1); + x.Conversion(); + x.Summation(2).CPUSummation(true).Compression(CompressionAlgorithm::BSHUF_LZ4); + REQUIRE(x.IsCPUSummation()); + + auto devices = Devices(x); + Logger logger("FPGAImagePuller_HostSummation"); + CollectingPusher pusher; + JFJochReceiverService service(devices, logger, pusher, 256); + service.NumThreads(4).SetSpotFindingSettings(Spots()); + service.UseFPGAImagePuller(FPGAImagePullerUse::Always); + PixelMask mask(x); + const JFCalibration calib = Calibration(x); + service.Start(x, mask, &calib); + const auto out = service.Stop(); + CHECK(out.efficiency == 1.0f); + CHECK(!out.received_packets.empty()); // only the FPGA receiver fills these + CHECK(out.status.images_collected == 2); +} + +// By default only a collection analysed by rugnux live goes through the puller: the others stay on the FPGA receiver +TEST_CASE("FPGAImagePuller_DefaultOnlyWithRugnuxLive", "[FPGAImagePuller]") { + auto x = Base(DetJF(1), 3, 1); + x.Conversion(); + x.Compression(CompressionAlgorithm::BSHUF_LZ4).FilePrefix("fpga_puller_default"); + + for (const bool rugnux: {false, true}) { + auto devices = Devices(x); + Logger logger("FPGAImagePuller_Default"); + CollectingPusher pusher; + JFJochReceiverService service(devices, logger, pusher, 256); + service.NumThreads(2).SetSpotFindingSettings(Spots()); + service.RugnuxLive(rugnux, nullptr, 2, 30); + PixelMask mask(x); + const JFCalibration calib = Calibration(x); + service.Start(x, mask, &calib); + const auto out = service.Stop(); + CHECK(out.status.images_sent == 3); + CHECK(out.received_packets.empty() == rugnux); // only the FPGA receiver fills these + } +} + +// JFJochReceiverRugnuxRotation takes the same stream, with its own forwarding thread. +TEST_CASE("FPGAImagePuller_RugnuxReceiver", "[FPGAImagePuller]") { + auto x = Base(DetJF(2), 6, 3); + x.Conversion(); + x.Compression(CompressionAlgorithm::BSHUF_LZ4); + x.Goniometer(GoniometerAxis("omega", 0, 0.1, Coord(-1, 0, 0), std::nullopt)); + x.FilePrefix("fpga_puller_rugnux"); + REQUIRE(RugnuxRotationData(x)); + + auto devices = MockDevices(x, CardImages(x, 3)); + Logger logger("FPGAImagePuller_Rugnux"); + CollectingPusher pusher; + JFJochReceiverService service(devices, logger, pusher, 256); + service.NumThreads(2).SetSpotFindingSettings(Spots()); + // Rugnux live takes the puller without being asked + service.RugnuxLive(true, nullptr, 2, 30); + + PixelMask mask(x); + const JFCalibration calib = Calibration(x); + service.Start(x, mask, &calib); + const auto out = service.Stop(); + std::cout << "rugnux receiver: efficiency " << out.efficiency << " sent " << out.status.images_sent + << " warning '" << out.analysis_warning << "'" << std::endl; + CHECK(out.efficiency == 1.0f); + CHECK(out.status.images_sent == 6); + CHECK(pusher.images.size() == 6); + CHECK(pusher.sequence.front() == "start"); + CHECK(pusher.sequence.back() == "end"); + CHECK(pusher.end.adu_histogram.contains("module0")); + CHECK_FALSE(pusher.sequence[1].starts_with("calibration")); // the writer gets calibration only from the FPGA receiver + const auto a = Pixels(pusher.images.at(0).message.image); + const auto b = Pixels(pusher.images.at(3).message.image); + CHECK(a == b); // the card output repeats after the third frame +} + +// In an unsigned image the card gives saturated and error pixels one value: the counts are the card's, on every receiver. +TEST_CASE("FPGAImagePuller_SaturatedAndErrorCountsFromTheCard", "[FPGAImagePuller]") { + auto x = Base(DetJF(2), 4, 2); + x.Conversion(); + x.Compression(CompressionAlgorithm::BSHUF_LZ4).BitDepthImage(16).PixelSigned(false).FilePrefix("fpga_puller_counts"); + const auto card = Run(x, false, 2); + + PathResult puller; + SECTION("JFJochReceiverLite") { + puller = Run(x, true, 2); + } + SECTION("JFJochReceiverRugnuxStills") { + puller = Run(x, true, 2, true); + } + SECTION("JFJochReceiverRugnuxRotation") { + auto rotation = x; + rotation.Goniometer(GoniometerAxis("omega", 0, 0.1, Coord(-1, 0, 0), std::nullopt)); + puller = Run(rotation, true, 2, true); + } + + REQUIRE(card.images.size() == 4); + REQUIRE(puller.images.size() == 4); + int64_t saturated = 0, error = 0; + for (const auto &[n, image]: puller.images) { + INFO("image " << n); + CHECK(image.message.saturated_pixel_count == card.images.at(n).message.saturated_pixel_count); + CHECK(image.message.error_pixel_count == card.images.at(n).message.error_pixel_count); + saturated += image.message.saturated_pixel_count.value_or(0); + error += image.message.error_pixel_count.value_or(0); + } + CHECK(saturated == 8); + CHECK(error == 8); +} + +// Rotation forwards the images unanalysed, so nothing would replace what the card's ROI map, not loaded for this run, gave. +TEST_CASE("FPGAImagePuller_NoStaleROI", "[FPGAImagePuller]") { + auto x = Base(DetJF(1), 4, 1); + x.Conversion(); + x.Compression(CompressionAlgorithm::BSHUF_LZ4); + x.Goniometer(GoniometerAxis("omega", 0, 0.1, Coord(-1, 0, 0), std::nullopt)); + x.FilePrefix("fpga_puller_roi"); + x.ROI().SetROI(ROIDefinition{.boxes = {ROIBox("box", 380, 450, 280, 320)}, .circles = {}, .azimuthal = {}}); + + auto devices = Devices(x); + Logger logger("FPGAImagePuller_NoStaleROI"); + CollectingPusher pusher; + JFJochReceiverService service(devices, logger, pusher, 256); + service.NumThreads(2).SetSpotFindingSettings(Spots()); + // Rugnux live takes the puller without being asked + service.RugnuxLive(true, nullptr, 2, 30); + + PixelMask mask(x); + const JFCalibration calib = Calibration(x); + service.Start(x, mask, &calib); + service.Stop(); + REQUIRE(pusher.images.size() == 4); + for (const auto &[n, image]: pusher.images) + CHECK(image.message.roi.empty()); +} + +// An image is many frames: efficiency and progress count images. +TEST_CASE("FPGAImagePuller_RugnuxReceiver_Summation", "[FPGAImagePuller]") { + auto x = Base(DetJF(1), 3, 2); + x.Conversion(); + x.Summation(2).Compression(CompressionAlgorithm::BSHUF_LZ4); + x.Goniometer(GoniometerAxis("omega", 0, 0.1, Coord(-1, 0, 0), std::nullopt)); + x.FilePrefix("fpga_puller_rugnux_sum"); + REQUIRE(x.GetImageNum() == 3); + REQUIRE(x.GetFrameNum() == 6); + + auto devices = Devices(x); + Logger logger("FPGAImagePuller_RugnuxSum"); + CollectingPusher pusher; + ImageBuffer buffer(256 * 1024 * 1024); + JFJochReceiverCurrentStatus status; + JFJochReceiverPlots plots; + RugnuxLiveStatus live; + PixelMask mask(x); + const JFCalibration calib = Calibration(x); + + FPGAImagePuller puller(x, mask, &calib, devices, logger, 2); + JFJochReceiverRugnuxRotation receiver(x, mask, puller, pusher, logger, 2, 2, nullptr, 30, false, live, Spots(), status, + plots, buffer); + receiver.StopReceiver(); + puller.Stop(); + CHECK(receiver.GetEfficiency() == 1.0f); + CHECK(receiver.GetProgress() == 1.0f); + CHECK(pusher.images.size() == 3); +} + +// The real writer: the master file states what the card did, not what a DECTRIS stream implies. +TEST_CASE("FPGAImagePuller_Writer", "[FPGAImagePuller]") { + RegisterHDF5Filter(); + auto x = Base(DetJF(2), 5, 2); + x.Conversion(); + x.Compression(CompressionAlgorithm::BSHUF_LZ4).ApplyPixelMask(true).ImagesPerFile(2) + .FilePrefix("fpga_image_puller_writer").SetFileWriterFormat(FileWriterFormat::NXmxVDS) + .OverwriteExistingFiles(true).SaveCalibration(true); + + auto devices = Devices(x); + Logger logger("FPGAImagePuller_Writer"); + HDF5FilePusher pusher; + JFJochReceiverService service(devices, logger, pusher, 256); + service.NumThreads(2).SetSpotFindingSettings(Spots()); + service.UseFPGAImagePuller(FPGAImagePullerUse::Always); + PixelMask mask(x); + const JFCalibration calib = Calibration(x); + service.Start(x, mask, &calib); + const auto out = service.Stop(); + CHECK(out.efficiency == 1.0f); + CHECK(out.writer_err.empty()); + CHECK(out.status.images_sent == 5); + + HDF5ReadOnlyFile master("fpga_image_puller_writer_master.h5"); + CHECK(master.GetBool("/entry/instrument/detector/pixel_mask_applied")); + HDF5DataSet dataset(master, "/entry/data/data"); + HDF5DataSpace space(dataset); + CHECK(space.GetDimensions()[0] == 5); + CHECK(space.GetDimensions()[1] == x.GetYPixelsNum()); +} diff --git a/tests/JFJochReceiverProcessingTest.cpp b/tests/JFJochReceiverProcessingTest.cpp index 312a92dd5..9012745f0 100644 --- a/tests/JFJochReceiverProcessingTest.cpp +++ b/tests/JFJochReceiverProcessingTest.cpp @@ -157,6 +157,8 @@ TEST_CASE("JFJochIntegrationTest_ZMQ_crystal_spot_and_index_GPUStills", "[JFJoch service.Indexing(experiment.GetIndexingSettings()); // Serial data with rugnux on: the converted frames are analysed on the GPU, after the pre-pass. service.RugnuxLive(true, nullptr, 4, 60); + // The default (FPGAImagePuller and JFJochReceiverRugnuxStills) and JFJochReceiverFPGA's own live stills + service.UseFPGAImagePuller(GENERATE(FPGAImagePullerUse::RugnuxLive, FPGAImagePullerUse::Never)); // No progress value at the start of measurement REQUIRE(!service.GetProgress().has_value()); @@ -234,6 +236,8 @@ TEST_CASE("JFJochIntegrationTest_ZMQ_GPUStills_writer_down", "[JFJochReceiver]") service.NumThreads(4); service.Indexing(experiment.GetIndexingSettings()); service.RugnuxLive(true, nullptr, 4, 60); + // The default (FPGAImagePuller and JFJochReceiverRugnuxStills) and JFJochReceiverFPGA's own live stills + service.UseFPGAImagePuller(GENERATE(FPGAImagePullerUse::RugnuxLive, FPGAImagePullerUse::Never)); service.Start(experiment, pixel_mask, nullptr); REQUIRE_THROWS_AS(service.Stop(), JFJochException); @@ -275,6 +279,8 @@ TEST_CASE("JFJochIntegrationTest_GPUStills_cancel_during_prepass", "[JFJochRecei service.NumThreads(4); service.Indexing(experiment.GetIndexingSettings()); service.RugnuxLive(true, nullptr, 4, 60); + // The default (FPGAImagePuller and JFJochReceiverRugnuxStills) and JFJochReceiverFPGA's own live stills + service.UseFPGAImagePuller(GENERATE(FPGAImagePullerUse::RugnuxLive, FPGAImagePullerUse::Never)); service.Start(experiment, pixel_mask, nullptr); std::this_thread::sleep_for(std::chrono::seconds(3)); From 65a3e05463840e8c202aecbaaf73effecbe1b69e Mon Sep 17 00:00:00 2001 From: Filip Leonarski Date: Wed, 18 Nov 2026 08:20:18 +0100 Subject: [PATCH 02/41] SqueezeToRawGeometry: an assembled JUNGFRAU image back to raw module frames The inverse of TransferModuleAdjustMultipixels: a raw pixel is the sum of the 2 (multipixel) or 4 (chip corner) assembled pixels its value was split over, as the split conserves the count; an error pixel among them makes it an error pixel, a saturated one or a sum past the destination's range a saturated one. ConvertedToRawGeometry takes one of them instead, which is right for masks and maps but halves the counts of the split pixels. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01UqXYdHHZ4cogS1mrGUtfN7 --- common/RawToConvertedGeometry.h | 12 +++++++ common/RawToConvertedGeometryCore.h | 50 ++++++++++++++++++++++++++++ tests/RawToConvertedGeometryTest.cpp | 35 +++++++++++++++++++ 3 files changed, 97 insertions(+) diff --git a/common/RawToConvertedGeometry.h b/common/RawToConvertedGeometry.h index a3a179f1f..21a997ca9 100644 --- a/common/RawToConvertedGeometry.h +++ b/common/RawToConvertedGeometry.h @@ -8,6 +8,18 @@ #include "Coord.h" #include "DiffractionExperiment.h" +// An assembled image back to raw module frames, the multipixels summed (SqueezeMultipixelsToModule) +template +void SqueezeToRawGeometry(const DiffractionExperiment &experiment, Td *destination, const Ts *source, + Ts min, Ts max, Td dest_min, Td dest_max) { + for (size_t module_number = 0; module_number < experiment.GetModulesNum(); module_number++) + SqueezeMultipixelsToModule(destination + module_number * RAW_MODULE_SIZE, source, + experiment.GetModuleSlowDirectionStep(module_number), min, max, + dest_min, dest_max, + experiment.GetModuleFastDirectionStep(module_number), + experiment.GetPixel0OfModuleConv(module_number)); +} + // Input coord is column + 1024 * (line + 512 * module) // Copies result over multipixel - can be used for example for mask calculation template diff --git a/common/RawToConvertedGeometryCore.h b/common/RawToConvertedGeometryCore.h index c7692f715..ca11dd33d 100644 --- a/common/RawToConvertedGeometryCore.h +++ b/common/RawToConvertedGeometryCore.h @@ -139,6 +139,56 @@ void TransferModuleAdjustMultipixels(Td *destination, const Ts *source, int64_t } } +// Inverse of TransferModuleAdjustMultipixels: each raw pixel of the module is the sum of the pixels its value was +// split over (2 for a multipixel, 4 at a chip corner), as the split conserves the count. A raw pixel is an error +// pixel where any of them is at or below min, saturated where any is at or above max or the sum reaches dest_max. +template +void SqueezeMultipixelsToModule(Td *destination, const Ts *source, int64_t slow_dir_step, Ts min, Ts max, + Td dest_min, Td dest_max, int64_t fast_dir_step = 1, int64_t offset_0 = 0) { + for (int64_t line = 0; line < RAW_MODULE_LINES; line++) { + int64_t y[2] = {line + ((line > 255) ? 2 : 0), -1}; + if (line == 255) + y[1] = 256; + else if (line == 256) + y[1] = 257; + + for (int64_t col = 0; col < RAW_MODULE_COLS; col++) { + const int64_t chip = col / 256, i = col % 256; + int64_t x[2] = {i + chip * 258, -1}; + if ((i == 255) && (chip < 3)) + x[1] = x[0] + 1; + else if ((i == 0) && (chip > 0)) + x[1] = x[0] - 1; + + int64_t sum = 0; + bool error = false, saturated = false; + for (int64_t yy: y) { + for (int64_t xx: x) { + if ((yy < 0) || (xx < 0)) + continue; + const Ts v = source[offset_0 + yy * slow_dir_step + xx * fast_dir_step]; + if (v <= min) + error = true; + else if (v >= max) + saturated = true; + else + sum += v; + } + } + + Td &out = destination[line * RAW_MODULE_COLS + col]; + if (error) + out = dest_min; + else if (saturated || (sum >= dest_max)) + out = dest_max; + else if (sum <= dest_min) + out = dest_min + 1; + else + out = static_cast(sum); + } + } +} + template void LineConvtToRaw(T *destination, const T *source, size_t fast_direction_step) { for (int chip = 0; chip < 4; chip++) { diff --git a/tests/RawToConvertedGeometryTest.cpp b/tests/RawToConvertedGeometryTest.cpp index 43e601e7e..5fa679486 100644 --- a/tests/RawToConvertedGeometryTest.cpp +++ b/tests/RawToConvertedGeometryTest.cpp @@ -517,3 +517,38 @@ TEST_CASE("RawToConvertedCoordinate_Coord","[RawToConvertedGeometry]") { REQUIRE(Catch::Approx(c.x) == CONVERTED_MODULE_COLS + 8 + 800.5 + 6); // col 800 becomes 806 due to 3 chip boundaries REQUIRE(Catch::Approx(c.y) == CONVERTED_MODULE_LINES * 2 + 36 - 1 - 300.25 - 2); // line 300 becomes 302 due to 1 chip boundary } + +TEST_CASE("RawToConvertedGeometry_SqueezeToRawGeometry","[RawToConvertedGeometry]") { + // Assembled with the multipixels split, then squeezed back: the raw frames, where the split divides evenly + DiffractionExperiment x(DetJF(4, 2, 8, 36, true)); + x.PixelSigned(true).BitDepthImage(16); + + std::vector raw(x.GetModulesNum() * RAW_MODULE_SIZE); + for (size_t i = 0; i < raw.size(); i++) + raw[i] = static_cast(4 * (i % 5000) - 400); + raw[255 * RAW_MODULE_COLS + 255] = INT16_MIN; // error, chip corner + raw[RAW_MODULE_SIZE + 10 * RAW_MODULE_COLS + 256] = INT16_MAX; // saturated, multipixel + + std::vector image(x.GetPixelsNum(), INT32_MIN); + for (int m = 0; m < x.GetModulesNum(); m++) + TransferModuleAdjustMultipixels(image.data(), raw.data() + m * RAW_MODULE_SIZE, + x.GetModuleSlowDirectionStep(m), INT16_MIN, INT16_MAX, + x.GetModuleFastDirectionStep(m), x.GetPixel0OfModuleConv(m)); + for (auto &v: image) { + if (v == INT16_MIN) + v = INT32_MIN; + else if (v == INT16_MAX) + v = INT32_MAX; + } + + std::vector squeezed(raw.size()); + SqueezeToRawGeometry(x, squeezed.data(), image.data(), INT32_MIN, INT32_MAX, + INT16_MIN, INT16_MAX); + CHECK(squeezed == raw); + + // A sum past the 16-bit range is saturated + image[x.GetPixel0OfModuleConv(0)] = 40000; + SqueezeToRawGeometry(x, squeezed.data(), image.data(), INT32_MIN, INT32_MAX, + INT16_MIN, INT16_MAX); + CHECK(squeezed[0] == INT16_MAX); +} From 8ca312f2970846d7447f510127aa1a31cf15f7f9 Mon Sep 17 00:00:00 2001 From: Filip Leonarski Date: Wed, 18 Nov 2026 08:20:18 +0100 Subject: [PATCH 03/41] jfjoch_fpga_stills_test: rugnux live stills on the card with a stored dataset A separate program (jfjoch_fpga_test is unchanged). The first images of a stored JUNGFRAU dataset (assembled, 8/36 px gaps; the layout from the image size) are squeezed back into module frames and loaded into the card's internal frame generator; the run is made with the conversion off, so the card returns them verbatim, and the host assembles them as signed 16-bit counts for rugnux live stills through FPGAImagePuller (-F: JFJochReceiverFPGA's live stills). Geometry, energy and cell from the file (-C overrides the cell). The generator holds what its memory and the 64-image generator setting allow and cycles through them for the whole run, so images repeat: throughput, latency, spots and indexing rate are what it measures, not the merge. It prints images collected/sent/dropped, frame rate, CPU use, indexing rate, spots per image, per-stage times, the pre-pass and its decisions, the analysis rate, the latency after the last image and rugnux's steps. -K runs it on MockAcquisitionDevice, whose generator memory is now a constructor argument (default 32 MiB as before); AcquisitionDevice exposes the module frames its generator memory holds. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01UqXYdHHZ4cogS1mrGUtfN7 --- acquisition_device/AcquisitionDevice.h | 1 + acquisition_device/MockAcquisitionDevice.cpp | 11 +- acquisition_device/MockAcquisitionDevice.h | 7 +- docs/TOOLS.md | 38 +++ tools/CMakeLists.txt | 4 + tools/jfjoch_fpga_stills_test.cpp | 280 +++++++++++++++++++ 6 files changed, 334 insertions(+), 7 deletions(-) create mode 100644 tools/jfjoch_fpga_stills_test.cpp diff --git a/acquisition_device/AcquisitionDevice.h b/acquisition_device/AcquisitionDevice.h index 9f6ed39d6..95da29371 100644 --- a/acquisition_device/AcquisitionDevice.h +++ b/acquisition_device/AcquisitionDevice.h @@ -123,5 +123,6 @@ public: void RunInternalGenerator(const DiffractionExperiment& experiment); // The module frame of the internal frame generator's images, throws if the card memory cannot hold it void CheckInternalGeneratorFrame(size_t module_frame) const; + uint64_t GetInternalGeneratorModuleFrames() const { return internal_generator_module_frames; } }; diff --git a/acquisition_device/MockAcquisitionDevice.cpp b/acquisition_device/MockAcquisitionDevice.cpp index 9c39f20bb..4d5a81f3c 100644 --- a/acquisition_device/MockAcquisitionDevice.cpp +++ b/acquisition_device/MockAcquisitionDevice.cpp @@ -6,9 +6,6 @@ #include "MockAcquisitionDevice.h" namespace { - // Memory of one HBM interface, as the HLS simulation has it: 64 module frames for the internal generator - constexpr uint32_t CardMemoryBytes = 32 * 1024 * 1024; - bool MaskEmpty(const uint64_t packet_mask[8]) { for (int i = 0; i < 8; i++) { if (packet_mask[i] != 0) @@ -18,8 +15,10 @@ namespace { } } -MockAcquisitionDevice::MockAcquisitionDevice(uint16_t data_stream, size_t in_frame_buffer_size_modules) +MockAcquisitionDevice::MockAcquisitionDevice(uint16_t data_stream, size_t in_frame_buffer_size_modules, + uint32_t in_card_memory_bytes) : FPGAAcquisitionDevice(data_stream), + card_memory_bytes(in_card_memory_bytes), collected_modules(2 * MAX_MODULES_FPGA), summation_completions(MAX_MODULES_FPGA * MAX_FPGA_SUMMATION), summation_mask(MAX_MODULES_FPGA, std::vector(MAX_FPGA_SUMMATION)), @@ -29,7 +28,7 @@ MockAcquisitionDevice::MockAcquisitionDevice(uint16_t data_stream, size_t in_fra ipv4_addr = 0x0132010A; max_modules = MAX_MODULES_FPGA; - internal_generator_module_frames = GeneratorModuleFrames(CardMemoryBytes); + internal_generator_module_frames = GeneratorModuleFrames(card_memory_bytes); generator_frames.resize(internal_generator_module_frames); buffers.reserve(in_frame_buffer_size_modules); @@ -534,7 +533,7 @@ DataCollectionStatus MockAcquisitionDevice::GetDataCollectionStatus() const { status.ctrl_reg = idle ? (1 << 4) : 0; status.max_modules = MAX_MODULES_FPGA; - status.hbm_size_bytes = CardMemoryBytes; + status.hbm_size_bytes = card_memory_bytes; status.run_counter = run_counter; status.current_pulseid = pulse_id; status.packets_udp = udp_packets; diff --git a/acquisition_device/MockAcquisitionDevice.h b/acquisition_device/MockAcquisitionDevice.h index a34d50f8e..b626136e4 100644 --- a/acquisition_device/MockAcquisitionDevice.h +++ b/acquisition_device/MockAcquisitionDevice.h @@ -62,6 +62,7 @@ class MockAcquisitionDevice : public FPGAAcquisitionDevice { uint32_t generator_slot; }; + const uint32_t card_memory_bytes; std::vector>> outputs; // The frames of the internal generator, by slot (module frame of the card memory) std::vector> generator_frames; @@ -123,7 +124,11 @@ class MockAcquisitionDevice : public FPGAAcquisitionDevice { void WriteToHost(const ModuleCompletion &c); void EndDataCollection(); public: - MockAcquisitionDevice(uint16_t data_stream, size_t in_frame_buffer_size_modules); + // Memory of one HBM interface, as the HLS simulation had it: 64 module frames for the internal generator + static constexpr uint32_t DefaultCardMemoryBytes = 32 * 1024 * 1024; + + MockAcquisitionDevice(uint16_t data_stream, size_t in_frame_buffer_size_modules, + uint32_t card_memory_bytes = DefaultCardMemoryBytes); ~MockAcquisitionDevice() override; void SetOutput(uint64_t image, uint32_t module_number, const DeviceOutput &output); diff --git a/docs/TOOLS.md b/docs/TOOLS.md index b8c577011..0edc53ff3 100644 --- a/docs/TOOLS.md +++ b/docs/TOOLS.md @@ -70,6 +70,44 @@ UDP packet simulator used to test the Jungfraujoch FPGA receiver. Exercises and benchmarks the FPGA data path and receiver. With `-H` it runs the high-level synthesis C model on the CPU, so no FPGA device is required. +### jfjoch_fpga_stills_test +Measures rugnux live stills on the FPGA card(s), with a stored dataset standing in for the detector: + +``` +jfjoch_fpga_stills_test [-i ] [-s ] [-N ] [-B ] [-C a,b,c,al,be,ga] [-X ] [-p ] [-F] [-K[]] +``` + +- The dataset must be a stored JUNGFRAU dataset, assembled with 8/36 pixel module gaps (as Jungfraujoch + writes it); the module layout is derived from the image size. Each image is folded back into module + frames, the inverse of the host's geometry transformation: the inter-chip pixels the assembled image + spreads one raw pixel over (2, or 4 at a chip corner) are summed back into it (the split conserves + the count); where one of them is an error, gap or masked pixel the raw pixel is an error pixel, where + one is saturated or the sum exceeds 16 bits it is saturated. +- The frames are loaded into the card's internal frame generator and the run is made with the JUNGFRAU + conversion off, so the card returns them verbatim; the host assembles them as signed 16-bit photon + counts and rugnux live stills analyses them through `FPGAImagePuller` (`-F`: through + `JFJochReceiverFPGA`'s own live stills, for comparison). Beam centre, distance, energy and the cell + come from the file (`-C` overrides the cell; without one the frames are indexed de novo). Nothing is + written. +- The generator holds only as many images as its card memory (and the 64-image limit of the + generator setting) allows: the first ones of the file, cycled for the whole run of `-i` images + (default: as many as the file has). **Images repeat**, so throughput, latency, spots per image and + indexing rate are meaningful, the merge and its statistics are not. The generator sends as fast as + the card can, faster than a detector: images the host cannot keep up with are dropped by the puller + and counted. +- At the end it prints images collected/sent/dropped, receiving time and frame rate, CPU use, indexing + rate and spots per image, per-image times of the analysis stages, the pre-pass (time, beam centre and + distance it decided), the analysis rate after it, the latency from the last image to the end of the + analysis and rugnux's steps. +- The image buffer (`-B`, MiB, default 16384) has to hold the pre-pass's frames + (`StillsGPUAnalysis::PREPASS_IMAGES`) in half its slots. +- `-K` runs on the mock of the card (`MockAcquisitionDevice`, which returns the generator's frames as + loaded) instead of `/dev/jfjoch*`, so the program runs without a card; the optional value is the mock's + generator memory in MiB. +- To compare with the offline analysis of the same images, run it with `-i` equal to the number of + distinct images it reports (no repeats) and `rugnux --force-still -e ` or + `jfjoch_stills_gpu_replay -n ` on the same file. + ### jfjoch_lite_perf_test Performance test of the lite (CPU/GPU) analysis path — spot finding, indexing and optional file writing. diff --git a/tools/CMakeLists.txt b/tools/CMakeLists.txt index cd951abd0..9fdf2e2a9 100644 --- a/tools/CMakeLists.txt +++ b/tools/CMakeLists.txt @@ -68,6 +68,10 @@ IF(NOT JFJOCH_PORTABLE_ONLY) TARGET_LINK_LIBRARIES(jfjoch_fpga_test JFJochReceiver) INSTALL(TARGETS jfjoch_fpga_test RUNTIME COMPONENT jfjoch) + ADD_EXECUTABLE(jfjoch_fpga_stills_test jfjoch_fpga_stills_test.cpp) + TARGET_LINK_LIBRARIES(jfjoch_fpga_stills_test JFJochReceiver JFJochReader) + INSTALL(TARGETS jfjoch_fpga_stills_test RUNTIME COMPONENT jfjoch) + ADD_EXECUTABLE(jfjoch_simplon_test jfjoch_simplon_test.cpp) TARGET_LINK_LIBRARIES(jfjoch_simplon_test JFJochDetector JFJochPreview) INSTALL(TARGETS jfjoch_simplon_test RUNTIME COMPONENT jfjoch) diff --git a/tools/jfjoch_fpga_stills_test.cpp b/tools/jfjoch_fpga_stills_test.cpp new file mode 100644 index 000000000..fcd73d91c --- /dev/null +++ b/tools/jfjoch_fpga_stills_test.cpp @@ -0,0 +1,280 @@ +// SPDX-FileCopyrightText: 2026 Filip Leonarski, Paul Scherrer Institute +// SPDX-License-Identifier: GPL-3.0-only + +// Rugnux live stills on the FPGA card(s), with a stored dataset as the detector: the first images of a JUNGFRAU +// dataset folded back into module frames, loaded into the card's internal frame generator and returned verbatim +// (no conversion), then assembled on the host and analysed through FPGAImagePuller and JFJochReceiverRugnuxStills. +// The generator cycles through the images its memory holds, so images repeat: throughput, latency and indexing rate +// are meaningful, the merge and its statistics are not. + +#include +#include +#include + +#include "../acquisition_device/PCIExpressDevice.h" +#include "../acquisition_device/MockAcquisitionDevice.h" +#include "../common/RawToConvertedGeometry.h" +#include "../common/print_license.h" +#include "../image_pusher/NonePusher.h" +#include "../reader/JFJochHDF5Reader.h" +#include "../receiver/JFJochReceiverService.h" +#include "../writer/HDF5Objects.h" + +void print_usage(Logger &logger) { + logger.Info("Usage ./jfjoch_fpga_stills_test {} "); + logger.Info("The dataset: JUNGFRAU modules, assembled with 8/36 pixel gaps. Its first images are loaded into"); + logger.Info("the card's internal generator, which cycles through them: images repeat, so throughput, latency"); + logger.Info("and indexing rate are meaningful, the merge and its statistics are not. See docs/TOOLS.md."); + logger.Info("Options:"); + logger.Info(" -v Verbose"); + logger.Info(" -i Images in the run (default: as many as the file has)"); + logger.Info(" -s Number of data streams (cards)"); + logger.Info(" -N Number of image processing threads (default 64)"); + logger.Info(" -B Size of the image buffer in MiB (default 16384)"); + logger.Info(" -C Unit cell (default: the file's)"); + logger.Info(" -X Indexing (auto|fft|fftw|ffbidx), auto is default"); + logger.Info(" -t Indexing thread pool size (default: 4)"); + logger.Info(" -p FPGAImagePuller slots (default 128)"); + logger.Info(" -F JFJochReceiverFPGA's own live stills instead of FPGAImagePuller"); + logger.Info(" -K{} Mock of the card instead of /dev/jfjoch* (optional: its generator memory, default 32 MiB)"); +} + +// The images the internal generator holds for this run: what the card memory holds, at most what the run needs +int64_t GeneratorImages(AcquisitionDeviceGroup &aq_devices, const DiffractionExperiment &x, int64_t file_images) { + int64_t ret = std::min(file_images, x.GetImageNum()); + ret = std::min(ret, 64); // DetectorSettings::InternalGeneratorImages + for (int i = 0; i < x.GetDataStreamsNum(); i++) + ret = std::min(ret, (aq_devices[i].GetInternalGeneratorModuleFrames() - 1) / x.GetModulesNum(i)); + return ret; +} + +// A stored dataset through the card and rugnux live stills; returns false where the run failed +bool RunDataset(Logger &logger, AcquisitionDeviceGroup &aq_devices, const std::string &file, + std::optional nimages, uint16_t nstreams, uint16_t nthreads, size_t send_buffer_size_MiB, + const IndexingSettings &indexing, const std::optional &cell, size_t puller_slots, + bool fpga_receiver) { + RegisterHDF5Filter(); + JFJochHDF5Reader reader; + reader.ReadFile(file); + const auto dataset = reader.GetDataset(); + const auto &file_x = dataset->experiment; + + // JUNGFRAU modules (1030 x 514 assembled) with the gaps of DetectorGeometryModular as the PSI detectors have them + const int64_t width = file_x.GetXPixelsNum(), height = file_x.GetYPixelsNum(); + const int64_t module_x = CONVERTED_MODULE_COLS + 8, module_y = CONVERTED_MODULE_LINES + 36; + const int64_t cols = (width + 8) / module_x, rows = (height + 36) / module_y; + if ((cols * module_x - 8 != width) || (rows * module_y - 36 != height)) { + logger.Error("Image {} x {} is not a JUNGFRAU module layout with 8/36 pixel gaps", width, height); + return false; + } + + DiffractionExperiment x(DetJF(cols * rows, cols, 8, 36, true)); + x.ImagesPerTrigger(nimages.value_or(reader.GetNumberOfImages())).NumTriggers(1).PedestalG0Frames(0) + .UseInternalPacketGenerator(true).DataStreams(nstreams); + // The card returns the frames as loaded; the host assembles them as signed 16-bit photon counts + x.JungfrauConvPhotonCnt(false).GeometryTransformation(true).PixelSigned(true).BitDepthImage(16); + x.Compression(CompressionAlgorithm::BSHUF_LZ4); + x.IncidentEnergy_keV(file_x.GetIncidentEnergy_keV()).DetectorDistance_mm(file_x.GetDetectorDistance_mm()) + .BeamX_pxl(file_x.GetBeamX_pxl()).BeamY_pxl(file_x.GetBeamY_pxl()); + x.SetUnitCell(cell ? cell : file_x.GetUnitCell()); + if (file_x.GetSpaceGroupNumber()) + x.SetSpaceGroup(file_x.GetSpaceGroupOrP1()); + x.ImportIndexingSettings(indexing); + + const int64_t generator_images = GeneratorImages(aq_devices, x, reader.GetNumberOfImages()); + if (generator_images < 1) { + logger.Error("The card memory cannot hold one image of {} modules", x.GetModulesNum()); + return false; + } + x.InternalPacketGeneratorImages(generator_images); + + PixelMask mask(x); + if (dataset->pixel_mask->GetMask().size() == x.GetPixelsNum()) + mask.LoadUserMask(x, dataset->pixel_mask->GetMask()); + + logger.Info("Dataset {}: {} images of {} modules ({} x {}), {} distinct ones in the generator, {} in the run", + file, reader.GetNumberOfImages(), x.GetModulesNum(), cols, rows, generator_images, x.GetImageNum()); + logger.Info("Mode: {}, rugnux live stills", fpga_receiver ? "JFJochReceiverFPGA" + : fmt::format("FPGAImagePuller ({} slots)", puller_slots)); + + NonePusher pusher; + JFJochReceiverService service(aq_devices, logger, pusher, send_buffer_size_MiB); + service.NumThreads(nthreads); + service.Indexing(x.GetIndexingSettings()); + service.RugnuxLive(true, nullptr, 4, 60); + service.UseFPGAImagePuller(fpga_receiver ? FPGAImagePullerUse::Never : FPGAImagePullerUse::RugnuxLive, + puller_slots); + + // Error, gap and beam-stop pixels of the reader become error pixels of the module frame + std::vector frame(x.GetModulesNum() * RAW_MODULE_SIZE); + std::vector frame_u16(frame.size()); + for (int64_t i = 0; i < generator_images; i++) { + const auto image = reader.LoadImage(i); + SqueezeToRawGeometry(x, frame.data(), image->Image().data(), BEAM_STOP_PXL_VALUE, + SATURATED_PXL_VALUE, INT16_MIN, INT16_MAX); + memcpy(frame_u16.data(), frame.data(), frame.size() * sizeof(int16_t)); + service.LoadInternalGeneratorImage(x, frame_u16, i); + } + + rusage usage_start{}; + getrusage(RUSAGE_SELF, &usage_start); + const auto wall_start = std::chrono::steady_clock::now(); + + service.Start(x, mask, nullptr); + const auto output = service.Stop(); + const auto live = service.GetRugnuxStatus(); + + const double wall_time = std::chrono::duration(std::chrono::steady_clock::now() - wall_start).count(); + rusage usage_end{}; + getrusage(RUSAGE_SELF, &usage_end); + auto seconds = [](const timeval &t) { return static_cast(t.tv_sec) + static_cast(t.tv_usec) / 1e6; }; + const double cpu_time = seconds(usage_end.ru_utime) - seconds(usage_start.ru_utime) + + seconds(usage_end.ru_stime) - seconds(usage_start.ru_stime); + const double receiving_time = static_cast(output.end_time_ms - output.start_time_ms) / 1000.0; + + int64_t spots = 0, spot_images = 0; + for (const auto &e: output.scan_result.images) + if (e.spot_count) { + spots += e.spot_count.value(); + spot_images++; + } + + logger.Info(""); + logger.Info("=== Summary ==="); + logger.Info("Images expected {} collected {} sent {} dropped by the puller {} efficiency {:.4f}", + x.GetImageNum(), output.status.images_collected, output.status.images_sent, + output.status.images_dropped, output.efficiency); + logger.Info("Receiving time {:.3f} s frame rate {:.1f} Hz wall time {:.3f} s CPU {:.1f} s = {:.1f} cores", + receiving_time, static_cast(x.GetImageNum()) / receiving_time, wall_time, cpu_time, + cpu_time / wall_time); + logger.Info("Indexing rate {:.3f} spots per image {:.1f}", output.status.indexing_rate.value_or(0), + static_cast(spots) / std::max(1, spot_images)); + logger.Info("Per-image time (mean; microseconds): preprocess {:.0f} spot finding {:.0f} indexing {:.0f} " + "refinement {:.0f} integration {:.0f} total {:.0f}", + output.processing_time.preprocessing * 1e6, output.processing_time.spot_finding * 1e6, + output.processing_time.indexing * 1e6, output.processing_time.refinement * 1e6, + output.processing_time.integration * 1e6, output.processing_time.processing * 1e6); + if (live.stills) { + const auto &st = *live.stills; + logger.Info("Pre-pass {:.2f} s: beam {:.2f} {:.2f} px (file {:.2f} {:.2f}), distance {:.2f} mm (file {:.2f})", + st.prepass_s.value_or(0), st.beam_x_pxl.value_or(NAN), st.beam_y_pxl.value_or(NAN), + st.file_beam_x_pxl, st.file_beam_y_pxl, st.distance_mm.value_or(NAN), st.file_distance_mm); + logger.Info("Analysed {} indexed {} analysis rate {:.1f} Hz", st.images_analysed, st.images_indexed, + st.analysis_rate_hz.value_or(0)); + } + logger.Info("Rugnux: {} {} space group {} last image at {:.2f} s, done {:.2f} s after it", + live.verdict, live.message, live.space_group, live.last_image_s.value_or(NAN), + live.last_image_to_written_s.value_or(NAN)); + for (const auto &step: live.steps) + logger.Info(" step {:.2f} s + {:.2f} s {}", step.started_s, step.duration_s.value_or(NAN), step.title); + logger.Info("Images repeat ({} distinct): the merge and its statistics are not a measure of the data", generator_images); + + return (output.efficiency > 0) && (live.state == RugnuxLiveState::Done); +} + +int main(int argc, char **argv) { + print_license("jfjoch_fpga_stills_test"); + + Logger logger("jfjoch_fpga_stills_test"); + logger.Verbose(true); + + uint16_t nstreams = 1; + uint16_t nthreads = 64; + size_t send_buffer_size_MiB = 16384; + std::optional nimages; + std::optional cell; + IndexingAlgorithmEnum indexing = IndexingAlgorithmEnum::Auto; + uint16_t indexing_threads = 4; + size_t puller_slots = FPGAImagePuller::DefaultSlots; + bool fpga_receiver = false; + std::optional mock_card_MiB; + bool verbose = false; + + int opt; + while ((opt = getopt(argc, argv, "vi:s:N:B:C:X:t:p:FK::")) != -1) { + switch (opt) { + case 'v': + verbose = true; + break; + case 'i': + nimages = atol(optarg); + break; + case 's': + nstreams = atol(optarg); + break; + case 'N': + nthreads = atol(optarg); + break; + case 'B': + send_buffer_size_MiB = atol(optarg); + break; + case 'C': { + UnitCell c{}; + if (sscanf(optarg, "%f,%f,%f,%f,%f,%f", &c.a, &c.b, &c.c, &c.alpha, &c.beta, &c.gamma) != 6) { + print_usage(logger); + exit(EXIT_FAILURE); + } + cell = c; + break; + } + case 'X': + if (std::string(optarg) == "fft" || std::string(optarg) == "FFT") + indexing = IndexingAlgorithmEnum::FFT; + else if (std::string(optarg) == "ffbidx" || std::string(optarg) == "FFBIDX") + indexing = IndexingAlgorithmEnum::FFBIDX; + else if (std::string(optarg) == "fftw" || std::string(optarg) == "FFTW") + indexing = IndexingAlgorithmEnum::FFTW; + else + indexing = IndexingAlgorithmEnum::Auto; + break; + case 't': + indexing_threads = atol(optarg); + break; + case 'p': + puller_slots = atol(optarg); + break; + case 'F': + fpga_receiver = true; + break; + case 'K': + mock_card_MiB = (optarg != nullptr) ? atol(optarg) + : MockAcquisitionDevice::DefaultCardMemoryBytes / (1024 * 1024); + break; + default: + print_usage(logger); + exit(EXIT_FAILURE); + } + } + + if (optind != argc - 1) { + print_usage(logger); + exit(EXIT_FAILURE); + } + + logger.Verbose(verbose); + + AcquisitionDeviceGroup aq_devices; + for (int i = 0; i < nstreams; i++) { + std::unique_ptr device; + if (mock_card_MiB) + device = std::make_unique(i, 128, mock_card_MiB.value() * 1024 * 1024); + else + device = std::make_unique(i, "/dev/jfjoch" + std::to_string(i)); + device->EnableLogging(&logger); + device->SetIPv4Address((i << 24) + 0x010a0a0a); + aq_devices.Add(std::move(device)); + } + + IndexingSettings i_settings; + i_settings.Algorithm(indexing); + i_settings.IndexingThreads(indexing_threads); + + bool ret = false; + try { + ret = RunDataset(logger, aq_devices, argv[optind], nimages, nstreams, nthreads, send_buffer_size_MiB, + i_settings, cell, puller_slots, fpga_receiver); + } catch (std::exception &e) { + logger.Error(e.what()); + } + exit(ret ? EXIT_SUCCESS : EXIT_FAILURE); +} From 4c8af0dbc1de12a8621a8ac78986d4297170c058 Mon Sep 17 00:00:00 2001 From: Filip Leonarski Date: Wed, 18 Nov 2026 09:43:57 +0100 Subject: [PATCH 04/41] FPGAImagePuller: frames given up on go back to the card while a module waits A module waiting for its next frame released the late frames of images it had given up on only after the wait. With one card more than MissingAfterFrames behind the others, its buffers filled with such frames, the card could not write the frame waited for, and the run hung (seen with two mock cards under load). The release now happens inside the wait. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01UqXYdHHZ4cogS1mrGUtfN7 --- receiver/FPGAImagePuller.cpp | 30 +++++++++++++++++------------- receiver/FPGAImagePuller.h | 2 +- 2 files changed, 18 insertions(+), 14 deletions(-) diff --git a/receiver/FPGAImagePuller.cpp b/receiver/FPGAImagePuller.cpp index f8244c995..3bc8b3aec 100644 --- a/receiver/FPGAImagePuller.cpp +++ b/receiver/FPGAImagePuller.cpp @@ -130,14 +130,23 @@ int64_t FPGAImagePuller::FastestFrame() const { return ret; } -// Polled: a dead card has to be noticed from the other cards' frames -void FPGAImagePuller::WaitForFrame(uint16_t data_stream, uint16_t module_number, int64_t frame) const { - const auto &counters = devices[data_stream].Counters(); - // A frame is complete once the module is two further on, as in JFJochReceiverFPGA - while ((static_cast(counters.GetCurrFrameNumber(module_number)) < frame + 2) - && !counters.IsAcquisitionFinished() && !failed - && (FastestFrame() < frame + 2 + MissingAfterFrames)) +// Polled: a dead card has to be noticed from the other cards' frames. +// A frame given up on can still arrive, late: its buffer goes back to the card, also while waiting, as the card +// may need it to write the frame waited for. +void FPGAImagePuller::WaitForFrame(uint16_t data_stream, uint16_t module_number, int64_t frame, int64_t &oldest_held) { + auto &device = devices[data_stream]; + const auto &counters = device.Counters(); + while (true) { + while ((oldest_held < frame) + && (oldest_held < static_cast(counters.GetCurrFrameNumber(module_number)))) + device.FrameBufferRelease(oldest_held++, module_number); + // A frame is complete once the module is two further on, as in JFJochReceiverFPGA + if ((static_cast(counters.GetCurrFrameNumber(module_number)) >= frame + 2) + || counters.IsAcquisitionFinished() || failed + || (FastestFrame() >= frame + 2 + MissingAfterFrames)) + return; std::this_thread::sleep_for(std::chrono::milliseconds(1)); + } } // The last frame any card got; waits for all cards, so every module stops at the same image @@ -185,7 +194,7 @@ void FPGAImagePuller::ModuleThread(uint16_t data_stream, uint16_t module_number) int64_t oldest_held = 0; for (int64_t image = 0; image < experiment.GetImageNum(); image++) { - WaitForFrame(data_stream, module_number, image); + WaitForFrame(data_stream, module_number, image, oldest_held); if (failed) break; @@ -195,11 +204,6 @@ void FPGAImagePuller::ModuleThread(uint16_t data_stream, uint16_t module_number) && (image > LastFrame())) break; - // A frame given up on can still arrive, late: its buffer goes back to the card. - while ((oldest_held < image) - && (oldest_held < static_cast(counters.GetCurrFrameNumber(module_number)))) - device.FrameBufferRelease(oldest_held++, module_number); - const bool collected = counters.IsAnyPacketCollected(image, module_number); if (const auto slot = GetSlot(image)) { if (collected) { diff --git a/receiver/FPGAImagePuller.h b/receiver/FPGAImagePuller.h index e02f272d1..422f60c87 100644 --- a/receiver/FPGAImagePuller.h +++ b/receiver/FPGAImagePuller.h @@ -72,7 +72,7 @@ private: void CompressThread(); void FinalizeMeasurement(); - void WaitForFrame(uint16_t data_stream, uint16_t module_number, int64_t frame) const; + void WaitForFrame(uint16_t data_stream, uint16_t module_number, int64_t frame, int64_t &oldest_held); int64_t FastestFrame() const; int64_t LastFrame() const; std::shared_ptr GetSlot(int64_t image_number); From 1135beb74e0723e1287add6a243a7948bea64fd6 Mon Sep 17 00:00:00 2001 From: Filip Leonarski Date: Wed, 18 Nov 2026 09:43:57 +0100 Subject: [PATCH 05/41] jfjoch_fpga_stills_test: the file's module layout, the firmware's generator limits - Layout from the file: its NXmx module groups, else the modules the gaps of its pixel mask mark (any placement and orientation of 1030 x 514 modules); a module without a stated readout direction is read out along its long side from its box's corner (the multipixels are symmetric, so the frames are the same). The file's modules also go to the analysis. - Distinct images per card = (its generator module frames - 1) / its modules, the run takes the smallest over the cards, at most FPGA_INTERNAL_GENERATOR_MAX_IMAGES (frame_cell, 128) and within FPGA_INTERNAL_GENERATOR_MAX_MODULE_FRAMES (mem_cell, 1024). The broker's 64-image limit stays: DetectorSettings::InternalGeneratorImages takes the maximum as a parameter, defaulting to it. The mapping (cards, modules, module frames used) is printed at start. - -K defaults to 64 MiB of mock generator memory = 128 module frames. - Squeeze round-trip tests for a 4M and a 9M layout and a 16-module layout with turned and standing modules. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01UqXYdHHZ4cogS1mrGUtfN7 --- common/DetectorSettings.cpp | 4 +- common/DetectorSettings.h | 4 +- common/DiffractionExperiment.cpp | 4 +- common/DiffractionExperiment.h | 3 +- docs/TOOLS.md | 15 +++-- fpga/pcie_driver/jfjoch_fpga.h | 3 + tests/RawToConvertedGeometryTest.cpp | 82 +++++++++++++++++++--------- tools/jfjoch_fpga_stills_test.cpp | 76 +++++++++++++++++++------- 8 files changed, 134 insertions(+), 57 deletions(-) diff --git a/common/DetectorSettings.cpp b/common/DetectorSettings.cpp index a4bf1c26e..2f30ccf63 100644 --- a/common/DetectorSettings.cpp +++ b/common/DetectorSettings.cpp @@ -13,9 +13,9 @@ DetectorSettings &DetectorSettings::InternalGeneratorEnable(bool input) { return *this; } -DetectorSettings &DetectorSettings::InternalGeneratorImages(int64_t input) { +DetectorSettings &DetectorSettings::InternalGeneratorImages(int64_t input, int64_t max_images) { check_min("Internal packet generator images", input, 1); - check_max("Internal packet generator images", input, 64); + check_max("Internal packet generator images", input, max_images); internal_fpga_packet_generator_images = input; return *this; } diff --git a/common/DetectorSettings.h b/common/DetectorSettings.h index dbd56f185..9a5034d65 100644 --- a/common/DetectorSettings.h +++ b/common/DetectorSettings.h @@ -37,7 +37,9 @@ class DetectorSettings { DetectorTiming timing = DetectorTiming::Trigger; public: DetectorSettings& InternalGeneratorEnable(bool input); - DetectorSettings& InternalGeneratorImages(int64_t input); + // The broker's limit; the firmware's own is FPGA_INTERNAL_GENERATOR_MAX_IMAGES + static constexpr int64_t DefaultMaxInternalGeneratorImages = 64; + DetectorSettings& InternalGeneratorImages(int64_t input, int64_t max_images = DefaultMaxInternalGeneratorImages); DetectorSettings& StorageCells(int64_t input); DetectorSettings& StorageCellStart(int64_t input); DetectorSettings& StorageCellDelay(const std::chrono::nanoseconds &input); diff --git a/common/DiffractionExperiment.cpp b/common/DiffractionExperiment.cpp index d31d4926e..e7917d146 100644 --- a/common/DiffractionExperiment.cpp +++ b/common/DiffractionExperiment.cpp @@ -1094,8 +1094,8 @@ float DiffractionExperiment::GetPhotonEnergyForConversion_keV() const { return GetIncidentEnergy_keV(); } -DiffractionExperiment &DiffractionExperiment::InternalPacketGeneratorImages(int64_t input) { - detector_settings.InternalGeneratorImages(input); +DiffractionExperiment &DiffractionExperiment::InternalPacketGeneratorImages(int64_t input, int64_t max_images) { + detector_settings.InternalGeneratorImages(input, max_images); return *this; } diff --git a/common/DiffractionExperiment.h b/common/DiffractionExperiment.h index e8e689642..f45e08fcd 100644 --- a/common/DiffractionExperiment.h +++ b/common/DiffractionExperiment.h @@ -119,7 +119,8 @@ public: DiffractionExperiment& ZMQPreviewPeriod(const std::optional &input); DiffractionExperiment& UseInternalPacketGenerator(bool input); - DiffractionExperiment& InternalPacketGeneratorImages(int64_t input); + DiffractionExperiment& InternalPacketGeneratorImages(int64_t input, + int64_t max_images = DetectorSettings::DefaultMaxInternalGeneratorImages); DiffractionExperiment& MaskModuleEdges(bool input); DiffractionExperiment& MaskChipEdges(bool input); diff --git a/docs/TOOLS.md b/docs/TOOLS.md index 0edc53ff3..75688e87d 100644 --- a/docs/TOOLS.md +++ b/docs/TOOLS.md @@ -77,8 +77,10 @@ Measures rugnux live stills on the FPGA card(s), with a stored dataset standing jfjoch_fpga_stills_test [-i ] [-s ] [-N ] [-B ] [-C a,b,c,al,be,ga] [-X ] [-p ] [-F] [-K[]] ``` -- The dataset must be a stored JUNGFRAU dataset, assembled with 8/36 pixel module gaps (as Jungfraujoch - writes it); the module layout is derived from the image size. Each image is folded back into module +- The dataset must be a stored JUNGFRAU dataset with its modules assembled (1030 x 514 each, any placement + and orientation): the layout is the file's - its NXmx module groups, else the modules the gaps of its pixel + mask mark (where the file does not give a module's readout direction, the module is read out from the + top-left corner of its box; the multipixels are symmetric, so the frames are the same). Each image is folded back into module frames, the inverse of the host's geometry transformation: the inter-chip pixels the assembled image spreads one raw pixel over (2, or 4 at a chip corner) are summed back into it (the split conserves the count); where one of them is an error, gap or masked pixel the raw pixel is an error pixel, where @@ -89,8 +91,11 @@ jfjoch_fpga_stills_test [-i ] [-s ] [-N ] [-B ] [-C `JFJochReceiverFPGA`'s own live stills, for comparison). Beam centre, distance, energy and the cell come from the file (`-C` overrides the cell; without one the frames are indexed de novo). Nothing is written. -- The generator holds only as many images as its card memory (and the 64-image limit of the - generator setting) allows: the first ones of the file, cycled for the whole run of `-i` images +- Each card's generator holds module frames of its own modules only: as many images as its memory holds + module frames (less one, which the host keeps free) divided by the modules of that card - e.g. 128 module + frames: a 9M (18 modules) on one card 7 images, on two cards of 9 modules 14. The run takes the smallest + over the cards (and at most 128, the firmware's image counter; the broker's limit of 64 images does not + apply here) and prints the mapping. These are the first ones of the file, cycled for the whole run of `-i` images (default: as many as the file has). **Images repeat**, so throughput, latency, spots per image and indexing rate are meaningful, the merge and its statistics are not. The generator sends as fast as the card can, faster than a detector: images the host cannot keep up with are dropped by the puller @@ -103,7 +108,7 @@ jfjoch_fpga_stills_test [-i ] [-s ] [-N ] [-B ] [-C (`StillsGPUAnalysis::PREPASS_IMAGES`) in half its slots. - `-K` runs on the mock of the card (`MockAcquisitionDevice`, which returns the generator's frames as loaded) instead of `/dev/jfjoch*`, so the program runs without a card; the optional value is the mock's - generator memory in MiB. + generator memory in MiB (default 64 MiB = 128 module frames). - To compare with the offline analysis of the same images, run it with `-i` equal to the number of distinct images it reports (no repeats) and `rugnux --force-still -e ` or `jfjoch_stills_gpu_replay -n ` on the same file. diff --git a/fpga/pcie_driver/jfjoch_fpga.h b/fpga/pcie_driver/jfjoch_fpga.h index 73efecf64..ca619841f 100644 --- a/fpga/pcie_driver/jfjoch_fpga.h +++ b/fpga/pcie_driver/jfjoch_fpga.h @@ -58,6 +58,9 @@ typedef __u64 uint64_t; // MAX_MODULES_FPGA is read by FPGA setup scripts and must be decimal, no expression! #define MAX_MODULES_FPGA 32 #define MAX_FPGA_SUMMATION 256 +// frame_generator.cpp: images in its memory (frame_cell, 7 bits) and module frames it addresses (mem_cell, 10 bits) +#define FPGA_INTERNAL_GENERATOR_MAX_IMAGES 128 +#define FPGA_INTERNAL_GENERATOR_MAX_MODULE_FRAMES 1024 #define ADU_HISTO_BIN_WIDTH 32 #define ADU_HISTO_BIN_COUNT (65536/ ADU_HISTO_BIN_WIDTH) diff --git a/tests/RawToConvertedGeometryTest.cpp b/tests/RawToConvertedGeometryTest.cpp index 5fa679486..28efb2bad 100644 --- a/tests/RawToConvertedGeometryTest.cpp +++ b/tests/RawToConvertedGeometryTest.cpp @@ -518,37 +518,65 @@ TEST_CASE("RawToConvertedCoordinate_Coord","[RawToConvertedGeometry]") { REQUIRE(Catch::Approx(c.y) == CONVERTED_MODULE_LINES * 2 + 36 - 1 - 300.25 - 2); // line 300 becomes 302 due to 1 chip boundary } -TEST_CASE("RawToConvertedGeometry_SqueezeToRawGeometry","[RawToConvertedGeometry]") { +namespace { // Assembled with the multipixels split, then squeezed back: the raw frames, where the split divides evenly - DiffractionExperiment x(DetJF(4, 2, 8, 36, true)); - x.PixelSigned(true).BitDepthImage(16); + void CheckSqueezeRoundTrip(const DetectorSetup &detector) { + DiffractionExperiment x(detector); + x.PixelSigned(true).BitDepthImage(16); - std::vector raw(x.GetModulesNum() * RAW_MODULE_SIZE); - for (size_t i = 0; i < raw.size(); i++) - raw[i] = static_cast(4 * (i % 5000) - 400); - raw[255 * RAW_MODULE_COLS + 255] = INT16_MIN; // error, chip corner - raw[RAW_MODULE_SIZE + 10 * RAW_MODULE_COLS + 256] = INT16_MAX; // saturated, multipixel + std::vector raw(x.GetModulesNum() * RAW_MODULE_SIZE); + for (size_t i = 0; i < raw.size(); i++) + raw[i] = static_cast(4 * (i % 5000) - 400); + raw[255 * RAW_MODULE_COLS + 255] = INT16_MIN; // error, chip corner + raw[RAW_MODULE_SIZE + 10 * RAW_MODULE_COLS + 256] = INT16_MAX; // saturated, multipixel - std::vector image(x.GetPixelsNum(), INT32_MIN); - for (int m = 0; m < x.GetModulesNum(); m++) - TransferModuleAdjustMultipixels(image.data(), raw.data() + m * RAW_MODULE_SIZE, - x.GetModuleSlowDirectionStep(m), INT16_MIN, INT16_MAX, - x.GetModuleFastDirectionStep(m), x.GetPixel0OfModuleConv(m)); - for (auto &v: image) { - if (v == INT16_MIN) - v = INT32_MIN; - else if (v == INT16_MAX) - v = INT32_MAX; + std::vector image(x.GetPixelsNum(), INT32_MIN); + for (int m = 0; m < x.GetModulesNum(); m++) + TransferModuleAdjustMultipixels(image.data(), raw.data() + m * RAW_MODULE_SIZE, + x.GetModuleSlowDirectionStep(m), INT16_MIN, INT16_MAX, + x.GetModuleFastDirectionStep(m), + x.GetPixel0OfModuleConv(m)); + for (auto &v: image) { + if (v == INT16_MIN) + v = INT32_MIN; + else if (v == INT16_MAX) + v = INT32_MAX; + } + + std::vector squeezed(raw.size()); + SqueezeToRawGeometry(x, squeezed.data(), image.data(), INT32_MIN, INT32_MAX, + INT16_MIN, INT16_MAX); + CHECK(squeezed == raw); + + // A sum past the 16-bit range is saturated + image[x.GetPixel0OfModuleConv(0)] = 40000; + SqueezeToRawGeometry(x, squeezed.data(), image.data(), INT32_MIN, INT32_MAX, + INT16_MIN, INT16_MAX); + CHECK(squeezed[0] == INT16_MAX); } +} - std::vector squeezed(raw.size()); - SqueezeToRawGeometry(x, squeezed.data(), image.data(), INT32_MIN, INT32_MAX, - INT16_MIN, INT16_MAX); - CHECK(squeezed == raw); +TEST_CASE("RawToConvertedGeometry_SqueezeToRawGeometry_4M","[RawToConvertedGeometry]") { + CheckSqueezeRoundTrip(DetJF(8, 2, 8, 36, true)); +} - // A sum past the 16-bit range is saturated - image[x.GetPixel0OfModuleConv(0)] = 40000; - SqueezeToRawGeometry(x, squeezed.data(), image.data(), INT32_MIN, INT32_MAX, - INT16_MIN, INT16_MAX); - CHECK(squeezed[0] == INT16_MAX); +TEST_CASE("RawToConvertedGeometry_SqueezeToRawGeometry_9M","[RawToConvertedGeometry]") { + CheckSqueezeRoundTrip(DetJF(18, 3, 8, 36, true)); +} + +TEST_CASE("RawToConvertedGeometry_SqueezeToRawGeometry_16_modules_turned","[RawToConvertedGeometry]") { + // 12 modules in rows of two, every other row read out the other way, and 4 standing modules beside them + using Direction = DetectorModuleGeometry::Direction; + std::vector modules; + for (int row = 0; row < 6; row++) + for (int col = 0; col < 2; col++) { + if (row % 2 == 0) + modules.emplace_back(col * 1038, row * 550, Direction::Xpos, Direction::Ypos); + else + modules.emplace_back(col * 1038 + 1029, row * 550 + 513, Direction::Xneg, Direction::Yneg); + } + for (int row = 0; row < 2; row++) + for (int col = 0; col < 2; col++) + modules.emplace_back(2076 + col * 522 + 513, row * 1038, Direction::Ypos, Direction::Xneg); + CheckSqueezeRoundTrip(DetJF(DetectorGeometryModular(modules))); } diff --git a/tools/jfjoch_fpga_stills_test.cpp b/tools/jfjoch_fpga_stills_test.cpp index fcd73d91c..2db0da20a 100644 --- a/tools/jfjoch_fpga_stills_test.cpp +++ b/tools/jfjoch_fpga_stills_test.cpp @@ -22,8 +22,9 @@ void print_usage(Logger &logger) { logger.Info("Usage ./jfjoch_fpga_stills_test {} "); - logger.Info("The dataset: JUNGFRAU modules, assembled with 8/36 pixel gaps. Its first images are loaded into"); - logger.Info("the card's internal generator, which cycles through them: images repeat, so throughput, latency"); + logger.Info("The dataset: JUNGFRAU modules, as the file states them (module groups, else the gaps of its mask)."); + logger.Info("Its first images - per card, as many as its generator memory holds of that card's modules - are"); + logger.Info("loaded into the cards' internal generators, which cycle through them: images repeat, so throughput, latency"); logger.Info("and indexing rate are meaningful, the merge and its statistics are not. See docs/TOOLS.md."); logger.Info("Options:"); logger.Info(" -v Verbose"); @@ -36,15 +37,44 @@ void print_usage(Logger &logger) { logger.Info(" -t Indexing thread pool size (default: 4)"); logger.Info(" -p FPGAImagePuller slots (default 128)"); logger.Info(" -F JFJochReceiverFPGA's own live stills instead of FPGAImagePuller"); - logger.Info(" -K{} Mock of the card instead of /dev/jfjoch* (optional: its generator memory, default 32 MiB)"); + logger.Info(" -K{} Mock of the card instead of /dev/jfjoch* (optional: its generator memory, default 64 MiB ="); + logger.Info(" 128 module frames)"); } -// The images the internal generator holds for this run: what the card memory holds, at most what the run needs +// A module the file gives the readout of keeps it; one it does not (taken from the gaps of its mask, +x +y) is read +// out from the top-left corner of its box, along its 1030-pixel side. As the multipixels are symmetric in a module, +// which corner it is does not change the frames the card returns. +std::optional GeometryFromModules(const DetectorModules &modules) { + using Direction = DetectorModuleGeometry::Direction; + auto along_x = [](Direction d) { return (d == Direction::Xpos) || (d == Direction::Xneg); }; + + std::vector ret; + for (const auto &m: modules.Get()) { + if ((m.width == CONVERTED_MODULE_COLS) && (m.height == CONVERTED_MODULE_LINES) && along_x(m.fast)) + ret.emplace_back(m.ReadoutX0(), m.ReadoutY0(), m.fast, m.slow); + else if ((m.width == CONVERTED_MODULE_LINES) && (m.height == CONVERTED_MODULE_COLS) && !along_x(m.fast)) + ret.emplace_back(m.ReadoutX0(), m.ReadoutY0(), m.fast, m.slow); + else if ((m.width == CONVERTED_MODULE_LINES) && (m.height == CONVERTED_MODULE_COLS)) + ret.emplace_back(m.x0, m.y0, Direction::Ypos, Direction::Xpos); + else + return {}; + } + if (ret.empty()) + return {}; + return DetectorGeometryModular(ret); +} + +// The images the internal generator holds for this run: what the card memory and the firmware hold (not the broker's +// limit), at most what the run needs int64_t GeneratorImages(AcquisitionDeviceGroup &aq_devices, const DiffractionExperiment &x, int64_t file_images) { int64_t ret = std::min(file_images, x.GetImageNum()); - ret = std::min(ret, 64); // DetectorSettings::InternalGeneratorImages - for (int i = 0; i < x.GetDataStreamsNum(); i++) - ret = std::min(ret, (aq_devices[i].GetInternalGeneratorModuleFrames() - 1) / x.GetModulesNum(i)); + ret = std::min(ret, FPGA_INTERNAL_GENERATOR_MAX_IMAGES); + for (int i = 0; i < x.GetDataStreamsNum(); i++) { + // CheckInternalGeneratorFrame leaves the last module frame of the card memory free + const int64_t module_frames = std::min(aq_devices[i].GetInternalGeneratorModuleFrames() - 1, + FPGA_INTERNAL_GENERATOR_MAX_MODULE_FRAMES); + ret = std::min(ret, module_frames / x.GetModulesNum(i)); + } return ret; } @@ -59,16 +89,17 @@ bool RunDataset(Logger &logger, AcquisitionDeviceGroup &aq_devices, const std::s const auto dataset = reader.GetDataset(); const auto &file_x = dataset->experiment; - // JUNGFRAU modules (1030 x 514 assembled) with the gaps of DetectorGeometryModular as the PSI detectors have them - const int64_t width = file_x.GetXPixelsNum(), height = file_x.GetYPixelsNum(); - const int64_t module_x = CONVERTED_MODULE_COLS + 8, module_y = CONVERTED_MODULE_LINES + 36; - const int64_t cols = (width + 8) / module_x, rows = (height + 36) / module_y; - if ((cols * module_x - 8 != width) || (rows * module_y - 36 != height)) { - logger.Error("Image {} x {} is not a JUNGFRAU module layout with 8/36 pixel gaps", width, height); + // The modules as the file states them (module groups, else the gaps of its mask) + const auto geometry = GeometryFromModules(file_x.GetModules()); + if (!geometry || (geometry->GetWidth(true) != file_x.GetXPixelsNum()) + || (geometry->GetHeight(true) != file_x.GetYPixelsNum())) { + logger.Error("The file does not state JUNGFRAU modules (1030 x 514) that make up its {} x {} image", + file_x.GetXPixelsNum(), file_x.GetYPixelsNum()); return false; } - DiffractionExperiment x(DetJF(cols * rows, cols, 8, 36, true)); + DiffractionExperiment x(DetJF(geometry.value())); + x.Modules(file_x.GetModules()); x.ImagesPerTrigger(nimages.value_or(reader.GetNumberOfImages())).NumTriggers(1).PedestalG0Frames(0) .UseInternalPacketGenerator(true).DataStreams(nstreams); // The card returns the frames as loaded; the host assembles them as signed 16-bit photon counts @@ -86,14 +117,22 @@ bool RunDataset(Logger &logger, AcquisitionDeviceGroup &aq_devices, const std::s logger.Error("The card memory cannot hold one image of {} modules", x.GetModulesNum()); return false; } - x.InternalPacketGeneratorImages(generator_images); + x.InternalPacketGeneratorImages(generator_images, FPGA_INTERNAL_GENERATOR_MAX_IMAGES); PixelMask mask(x); if (dataset->pixel_mask->GetMask().size() == x.GetPixelsNum()) mask.LoadUserMask(x, dataset->pixel_mask->GetMask()); - logger.Info("Dataset {}: {} images of {} modules ({} x {}), {} distinct ones in the generator, {} in the run", - file, reader.GetNumberOfImages(), x.GetModulesNum(), cols, rows, generator_images, x.GetImageNum()); + logger.Info("Dataset {}: {} images of {} modules, {} distinct ones in the generator, {} in the run", + file, reader.GetNumberOfImages(), x.GetModulesNum(), generator_images, x.GetImageNum()); + for (int i = 0; i < x.GetDataStreamsNum(); i++) + logger.Info(" card {}: modules {}-{}, generator memory {} module frames, {} used", i, + x.GetFirstModuleOfDataStream(i), x.GetFirstModuleOfDataStream(i) + x.GetModulesNum(i) - 1, + aq_devices[i].GetInternalGeneratorModuleFrames(), x.GetModulesNum(i) * generator_images); + for (int m = 0; m < x.GetModulesNum(); m++) + logger.Debug(" module {}: pixel 0 at ({}, {}), fast step {}, slow step {}", m, + x.GetPixel0OfModuleConv(m) % x.GetXPixelsNum(), x.GetPixel0OfModuleConv(m) / x.GetXPixelsNum(), + x.GetModuleFastDirectionStep(m), x.GetModuleSlowDirectionStep(m)); logger.Info("Mode: {}, rugnux live stills", fpga_receiver ? "JFJochReceiverFPGA" : fmt::format("FPGAImagePuller ({} slots)", puller_slots)); @@ -237,8 +276,7 @@ int main(int argc, char **argv) { fpga_receiver = true; break; case 'K': - mock_card_MiB = (optarg != nullptr) ? atol(optarg) - : MockAcquisitionDevice::DefaultCardMemoryBytes / (1024 * 1024); + mock_card_MiB = (optarg != nullptr) ? atol(optarg) : 64; break; default: print_usage(logger); From d4b1ac88524b42fd878b392ffcac639d576cebb4 Mon Sep 17 00:00:00 2001 From: Filip Leonarski Date: Wed, 18 Nov 2026 09:58:03 +0100 Subject: [PATCH 06/41] jfjoch_fpga_stills_test: blocking at the source, paced rate sweep FPGAImagePuller gains two options, off by default (the broker is unchanged): - blocking: an image waits for a free slot instead of being dropped, and no module is given up for being behind the others; JFJochReceiverRugnuxStills then waits for room in the image buffer (ImagePuller::IsBlocking). The cards keep their frames, host_writer waits for host buffers and the stall reaches the internal generator through the AXI-stream back-pressure, so nothing is lost anywhere. The time the module threads waited for a slot is kept. - frame_rate_hz: image i is taken from the cards no earlier than i / rate after the start. The firmware has no frame period for the generator, so this is how it is paced. GetSlot now looks for the image again after each wait (another module may have started it). jfjoch_fpga_stills_test always blocks; -r runs one collection per rate and reports delivered rate, the fraction of it the source was blocked, sustained rate (images / wall time), analysis rate after the pre-pass, indexing rate, and the card's cycles waiting for host buffers; a table at the end. The mock counts its wait for host buffers as pipeline_stalls_host, like timer_host. Tests: FPGAImagePuller_SlowConsumer_Blocking (no drop, all images in order), FPGAImagePuller_Paced. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01UqXYdHHZ4cogS1mrGUtfN7 --- acquisition_device/MockAcquisitionDevice.cpp | 5 + acquisition_device/MockAcquisitionDevice.h | 1 + docs/TOOLS.md | 26 ++- image_puller/ImagePuller.h | 2 + receiver/FPGAImagePuller.cpp | 51 ++++-- receiver/FPGAImagePuller.h | 13 +- receiver/JFJochReceiverRugnuxStills.cpp | 4 + receiver/JFJochReceiverService.cpp | 13 +- receiver/JFJochReceiverService.h | 8 +- tests/FPGAImagePullerTest.cpp | 63 +++++++ tools/jfjoch_fpga_stills_test.cpp | 166 ++++++++++++------- 11 files changed, 268 insertions(+), 84 deletions(-) diff --git a/acquisition_device/MockAcquisitionDevice.cpp b/acquisition_device/MockAcquisitionDevice.cpp index 4d5a81f3c..b4fb3bb69 100644 --- a/acquisition_device/MockAcquisitionDevice.cpp +++ b/acquisition_device/MockAcquisitionDevice.cpp @@ -267,6 +267,7 @@ int MockAcquisitionDevice::FrameGenerator(FrameGeneratorConfig config) { void MockAcquisitionDevice::DataCollectionThread() { cancel = false; stop_frame_generator = false; + stalls_host = 0; for (auto &c: collected_modules) c = ModuleCompletion{.frame_number = UINT64_MAX}; @@ -455,11 +456,14 @@ void MockAcquisitionDevice::WriteToHost(const ModuleCompletion &c) { // host_writer.cpp: waits for a host buffer; only when the data collection is cancelled the module // is dropped instead uint32_t handle; + const auto t0 = std::chrono::steady_clock::now(); while (!work_requests.Get(handle)) { if (cancel) return; std::this_thread::sleep_for(std::chrono::microseconds(10)); } + // timer_host: the wait in cycles of the card's 200 MHz clock + stalls_host += std::chrono::duration_cast(std::chrono::steady_clock::now() - t0).count() / 5; if (handle >= buffer_device.size()) return; DeviceOutput *output = buffer_device[handle]; @@ -538,6 +542,7 @@ DataCollectionStatus MockAcquisitionDevice::GetDataCollectionStatus() const { status.current_pulseid = pulse_id; status.packets_udp = udp_packets; status.packets_sls = sls_packets; + status.pipeline_stalls_host = stalls_host; return status; } diff --git a/acquisition_device/MockAcquisitionDevice.h b/acquisition_device/MockAcquisitionDevice.h index b626136e4..97757c718 100644 --- a/acquisition_device/MockAcquisitionDevice.h +++ b/acquisition_device/MockAcquisitionDevice.h @@ -100,6 +100,7 @@ class MockAcquisitionDevice : public FPGAAcquisitionDevice { std::atomic current_pulse_id = UINT64_MAX; std::atomic udp_packets = 0; std::atomic sls_packets = 0; + std::atomic stalls_host = 0; void HW_ReadActionRegister(DataCollectionConfig *job) override; void HW_WriteActionRegister(const DataCollectionConfig *job) override; diff --git a/docs/TOOLS.md b/docs/TOOLS.md index 75688e87d..14e9debec 100644 --- a/docs/TOOLS.md +++ b/docs/TOOLS.md @@ -74,7 +74,7 @@ synthesis C model on the CPU, so no FPGA device is required. Measures rugnux live stills on the FPGA card(s), with a stored dataset standing in for the detector: ``` -jfjoch_fpga_stills_test [-i ] [-s ] [-N ] [-B ] [-C a,b,c,al,be,ga] [-X ] [-p ] [-F] [-K[]] +jfjoch_fpga_stills_test [-i ] [-s ] [-N ] [-B ] [-C a,b,c,al,be,ga] [-X ] [-r ,...] [-p ] [-F] [-K[]] ``` - The dataset must be a stored JUNGFRAU dataset with its modules assembled (1030 x 514 each, any placement @@ -88,7 +88,8 @@ jfjoch_fpga_stills_test [-i ] [-s ] [-N ] [-B ] [-C - The frames are loaded into the card's internal frame generator and the run is made with the JUNGFRAU conversion off, so the card returns them verbatim; the host assembles them as signed 16-bit photon counts and rugnux live stills analyses them through `FPGAImagePuller` (`-F`: through - `JFJochReceiverFPGA`'s own live stills, for comparison). Beam centre, distance, energy and the cell + `JFJochReceiverFPGA`'s own live stills, for comparison; that path does not block: frames past what its + analysis holds are lost and counted). Beam centre, distance, energy and the cell come from the file (`-C` overrides the cell; without one the frames are indexed de novo). Nothing is written. - Each card's generator holds module frames of its own modules only: as many images as its memory holds @@ -97,13 +98,24 @@ jfjoch_fpga_stills_test [-i ] [-s ] [-N ] [-B ] [-C over the cards (and at most 128, the firmware's image counter; the broker's limit of 64 images does not apply here) and prints the mapping. These are the first ones of the file, cycled for the whole run of `-i` images (default: as many as the file has). **Images repeat**, so throughput, latency, spots per image and - indexing rate are meaningful, the merge and its statistics are not. The generator sends as fast as - the card can, faster than a detector: images the host cannot keep up with are dropped by the puller - and counted. + indexing rate are meaningful, the merge and its statistics are not. +- The run blocks at the source, no image is dropped: `FPGAImagePuller` waits for a free slot instead of + dropping an image (and gives no module up for being behind the others), the stills receiver waits for + room in the image buffer, so the card keeps its frames, its host writer waits for host buffers and the + stall reaches the internal generator through the card's AXI-stream back-pressure (the generator sits + before the network stack; a real detector's UDP packets would be lost at that point instead). The + firmware cannot pace the generator (it has no frame period): `-r` paces it from the host, the puller + taking image *i* from the cards no earlier than *i / rate* after the start, so the card waits for the + host either way. One collection is run per rate of `-r` (default `0`, as fast as it goes). +- For each rate it reports the rate images were delivered (first to last image), the fraction of that time + the source was blocked by the chain behind it (the time the puller's module threads waited for a free + slot, mean over the modules), the sustained rate (images / wall time, start to the end of the analysis) + and the analysis rate after the pre-pass, and at the end a table of them: the highest rate with ~0% + blocked is the rate the live stills chain sustains. The card's own count of the cycles it waited for host + buffers is printed too; with `-r` it includes the pacing. - At the end it prints images collected/sent/dropped, receiving time and frame rate, CPU use, indexing rate and spots per image, per-image times of the analysis stages, the pre-pass (time, beam centre and - distance it decided), the analysis rate after it, the latency from the last image to the end of the - analysis and rugnux's steps. + distance it decided), the latency from the last image to the end of the analysis and rugnux's steps. - The image buffer (`-B`, MiB, default 16384) has to hold the pre-pass's frames (`StillsGPUAnalysis::PREPASS_IMAGES`) in half its slots. - `-K` runs on the mock of the card (`MockAcquisitionDevice`, which returns the generator's frames as diff --git a/image_puller/ImagePuller.h b/image_puller/ImagePuller.h index fec35d311..4915bfbd7 100644 --- a/image_puller/ImagePuller.h +++ b/image_puller/ImagePuller.h @@ -78,6 +78,8 @@ public: // Images the puller had no room for, which the receiver therefore never gets. virtual size_t GetDroppedImages() const { return 0; } + // The source waits for the receiver rather than lose an image: the receiver waits for room instead of dropping it + virtual bool IsBlocking() const { return false; } }; diff --git a/receiver/FPGAImagePuller.cpp b/receiver/FPGAImagePuller.cpp index 3bc8b3aec..26eacc4c0 100644 --- a/receiver/FPGAImagePuller.cpp +++ b/receiver/FPGAImagePuller.cpp @@ -9,12 +9,15 @@ FPGAImagePuller::FPGAImagePuller(const DiffractionExperiment &in_experiment, const PixelMask &mask, const JFCalibration *calibration, AcquisitionDeviceGroup &in_devices, - Logger &in_logger, int64_t compression_threads, size_t in_max_slots) + Logger &in_logger, int64_t compression_threads, size_t in_max_slots, + bool in_blocking, double in_frame_rate_hz) : ImagePuller(in_max_slots + 2), // every slot, the start and the end message: Put never finds it full experiment(in_experiment), logger(in_logger), devices(in_devices), max_slots(in_max_slots), + blocking(in_blocking), + frame_rate_hz(in_frame_rate_hz), image_dropped(experiment.GetImageNum(), 0) { const int ndatastreams = experiment.GetDataStreamsNum(); if (devices.size() < ndatastreams) @@ -42,6 +45,7 @@ FPGAImagePuller::FPGAImagePuller(const DiffractionExperiment &in_experiment, con outside_fifo.Put({.cbor = std::make_shared(start), .received = std::chrono::steady_clock::now()}); + start_time = std::chrono::steady_clock::now(); for (int i = 0; i < compression_threads; i++) compress_futures.emplace_back(std::async(std::launch::async, &FPGAImagePuller::CompressThread, this)); @@ -143,7 +147,7 @@ void FPGAImagePuller::WaitForFrame(uint16_t data_stream, uint16_t module_number, // A frame is complete once the module is two further on, as in JFJochReceiverFPGA if ((static_cast(counters.GetCurrFrameNumber(module_number)) >= frame + 2) || counters.IsAcquisitionFinished() || failed - || (FastestFrame() >= frame + 2 + MissingAfterFrames)) + || (!blocking && (FastestFrame() >= frame + 2 + MissingAfterFrames))) return; std::this_thread::sleep_for(std::chrono::milliseconds(1)); } @@ -159,20 +163,27 @@ int64_t FPGAImagePuller::LastFrame() const { std::shared_ptr FPGAImagePuller::GetSlot(int64_t image_number) { std::unique_lock ul(images_mutex); - if (image_dropped[image_number]) - return nullptr; - if (const auto it = images_in_progress.find(image_number); it != images_in_progress.end()) - return it->second; - std::shared_ptr slot; - if (!free_slots.empty()) { - slot = free_slots.back(); - free_slots.pop_back(); - } else { - image_dropped[image_number] = 1; - dropped_images++; - Emit(image_number, std::nullopt); - return nullptr; + while (!slot) { + if (image_dropped[image_number]) + return nullptr; + // Another module may have started the image while this one waited + if (const auto it = images_in_progress.find(image_number); it != images_in_progress.end()) + return it->second; + if (!free_slots.empty()) { + slot = free_slots.back(); + free_slots.pop_back(); + } else if (blocking && !failed) { + const auto t0 = std::chrono::steady_clock::now(); + slot_returned.wait_for(ul, std::chrono::milliseconds(10)); + slot_wait_ns += std::chrono::duration_cast( + std::chrono::steady_clock::now() - t0).count(); + } else { + image_dropped[image_number] = 1; + dropped_images++; + Emit(image_number, std::nullopt); + return nullptr; + } } slot->image_number = image_number; slot->metadata = std::make_unique(experiment); @@ -182,8 +193,11 @@ std::shared_ptr FPGAImagePuller::GetSlot(int64_t image_nu } void FPGAImagePuller::ReturnSlot(const std::shared_ptr &slot) { - std::unique_lock ul(images_mutex); - free_slots.push_back(slot); + { + std::unique_lock ul(images_mutex); + free_slots.push_back(slot); + } + slot_returned.notify_one(); } void FPGAImagePuller::ModuleThread(uint16_t data_stream, uint16_t module_number) { @@ -194,6 +208,9 @@ void FPGAImagePuller::ModuleThread(uint16_t data_stream, uint16_t module_number) int64_t oldest_held = 0; for (int64_t image = 0; image < experiment.GetImageNum(); image++) { + if (frame_rate_hz > 0) + std::this_thread::sleep_until(start_time + std::chrono::duration_cast( + std::chrono::duration(static_cast(image) / frame_rate_hz))); WaitForFrame(data_stream, module_number, image, oldest_held); if (failed) diff --git a/receiver/FPGAImagePuller.h b/receiver/FPGAImagePuller.h index 422f60c87..844a839f5 100644 --- a/receiver/FPGAImagePuller.h +++ b/receiver/FPGAImagePuller.h @@ -4,6 +4,7 @@ #pragma once #include +#include #include #include #include @@ -40,6 +41,13 @@ private: Logger &logger; AcquisitionDeviceGroup &devices; const size_t max_slots; + // Blocking: an image waits for a free slot instead of being dropped, and no module is given up for being behind + // the others, so the cards hold their frames and stall at the source. + const bool blocking; + const double frame_rate_hz; // images taken from the cards at most at this rate (0: as they come) + std::chrono::steady_clock::time_point start_time; + std::condition_variable slot_returned; + std::atomic slot_wait_ns = 0; uint64_t expected_packets_per_image = 0; std::mutex images_mutex; @@ -82,11 +90,14 @@ public: // Arms the cards; when it returns the detector can be started. FPGAImagePuller(const DiffractionExperiment &experiment, const PixelMask &mask, const JFCalibration *calibration, AcquisitionDeviceGroup &devices, Logger &logger, int64_t compression_threads, - size_t max_slots = DefaultSlots); + size_t max_slots = DefaultSlots, bool blocking = false, double frame_rate_hz = 0); ~FPGAImagePuller() override; void Disconnect() override {} size_t GetDroppedImages() const override { return dropped_images; } + bool IsBlocking() const override { return blocking; } + // Time the module threads waited for a free slot, summed over them + double GetSlotWaitTime_s() const { return static_cast(slot_wait_ns) * 1e-9; } // The collection is over, whatever the cards have got: what is on its way still comes, then the end message. void Cancel(); diff --git a/receiver/JFJochReceiverRugnuxStills.cpp b/receiver/JFJochReceiverRugnuxStills.cpp index f9dcf5260..f14ac33ab 100644 --- a/receiver/JFJochReceiverRugnuxStills.cpp +++ b/receiver/JFJochReceiverRugnuxStills.cpp @@ -85,6 +85,10 @@ void JFJochReceiverRugnuxStills::OnImage(uint32_t id, DataMessage &message, std: // Waits for the analysis in a slot of the image buffer; a slot is kept free for each analysis thread to send with auto held = std::make_shared(); held->slot = image_buffer.GetImageSlot(stills_keep_free); + while ((held->slot == nullptr) && image_puller.IsBlocking() && !cancelled) { + std::this_thread::sleep_for(std::chrono::milliseconds(1)); + held->slot = image_buffer.GetImageSlot(stills_keep_free); + } if (held->slot == nullptr) { writer_queue_full = true; return; diff --git a/receiver/JFJochReceiverService.cpp b/receiver/JFJochReceiverService.cpp index 724e65e15..54a6eb618 100644 --- a/receiver/JFJochReceiverService.cpp +++ b/receiver/JFJochReceiverService.cpp @@ -38,16 +38,24 @@ JFJochReceiverService &JFJochReceiverService::RugnuxLive(bool enable, std::share return *this; } -JFJochReceiverService &JFJochReceiverService::UseFPGAImagePuller(FPGAImagePullerUse use, size_t slots) { +JFJochReceiverService &JFJochReceiverService::UseFPGAImagePuller(FPGAImagePullerUse use, size_t slots, bool blocking, + double frame_rate_hz) { std::unique_lock ul_state(state_mutex); if (state != ReceiverState::Idle) throw JFJochException(JFJochExceptionCategory::WrongDAQState, "Cannot change the receiver path during data collection"); fpga_image_puller = use; fpga_image_puller_slots = slots; + fpga_image_puller_blocking = blocking; + fpga_image_puller_rate_hz = frame_rate_hz; return *this; } +double JFJochReceiverService::GetFPGAImagePullerSlotWaitTime_s() const { + std::unique_lock ul(state_mutex); + return fpga_puller ? fpga_puller->GetSlotWaitTime_s() : 0.0; +} + // Pedestal runs and summation on the host need JFJochReceiverFPGA bool JFJochReceiverService::FPGAImagePullerFor(const DiffractionExperiment &experiment) const { if ((experiment.GetDetectorType() == DetectorType::DECTRIS) || experiment.IsPedestalRun() @@ -142,7 +150,8 @@ void JFJochReceiverService::Start(const DiffractionExperiment &experiment, // A PSI detector's frames through FPGAImagePuller go to the stream receivers, as a DECTRIS stream does if (FPGAImagePullerFor(experiment)) { fpga_puller = std::make_shared(experiment, pixel_mask, calibration, aq_devices, logger, - nthreads, fpga_image_puller_slots); + nthreads, fpga_image_puller_slots, + fpga_image_puller_blocking, fpga_image_puller_rate_hz); puller = fpga_puller; } diff --git a/receiver/JFJochReceiverService.h b/receiver/JFJochReceiverService.h index d11d2c818..c8a6a7f65 100644 --- a/receiver/JFJochReceiverService.h +++ b/receiver/JFJochReceiverService.h @@ -46,6 +46,8 @@ class JFJochReceiverService { // Which PSI collections go through FPGAImagePuller and the stream receivers FPGAImagePullerUse fpga_image_puller = FPGAImagePullerUse::RugnuxLive; size_t fpga_image_puller_slots = FPGAImagePuller::DefaultSlots; + bool fpga_image_puller_blocking = false; + double fpga_image_puller_rate_hz = 0; std::shared_ptr fpga_puller; bool FPGAImagePullerFor(const DiffractionExperiment &experiment) const; @@ -75,7 +77,11 @@ public: double deadline_s, bool refine_solvent = false, bool force_still = false); RugnuxLiveSnapshot GetRugnuxStatus() const; void ClearRugnuxStatus(); // back to Idle, as before any collection - JFJochReceiverService& UseFPGAImagePuller(FPGAImagePullerUse use, size_t slots = FPGAImagePuller::DefaultSlots); + // blocking, frame_rate_hz: see FPGAImagePuller + JFJochReceiverService& UseFPGAImagePuller(FPGAImagePullerUse use, size_t slots = FPGAImagePuller::DefaultSlots, + bool blocking = false, double frame_rate_hz = 0); + // Of the last collection through FPGAImagePuller: FPGAImagePuller::GetSlotWaitTime_s, 0 without one + double GetFPGAImagePullerSlotWaitTime_s() const; JFJochReceiverService& PreviewSocket(const std::string &addr, const std::optional &watermark = {}); JFJochReceiverService& MetadataSocket(const std::string &addr); diff --git a/tests/FPGAImagePullerTest.cpp b/tests/FPGAImagePullerTest.cpp index f7bf6b89a..37027ba1d 100644 --- a/tests/FPGAImagePullerTest.cpp +++ b/tests/FPGAImagePullerTest.cpp @@ -466,6 +466,69 @@ TEST_CASE("FPGAImagePuller_SlowConsumer_Puller", "[FPGAImagePuller]") { CHECK(numbers[i] > numbers[i - 1]); } +// Blocking: the same slow consumer, nothing is dropped - the card waits for its buffers instead +TEST_CASE("FPGAImagePuller_SlowConsumer_Blocking", "[FPGAImagePuller]") { + auto x = Base(DetJF(1), 20, 1); + x.Conversion(); + x.Compression(CompressionAlgorithm::BSHUF_LZ4); + + auto devices = Devices(x); + Logger logger("FPGAImagePuller_SlowConsumer_Blocking"); + PixelMask mask(x); + const JFCalibration calib = Calibration(x); + FPGAImagePuller puller(x, mask, &calib, devices, logger, 2, 4, true); + REQUIRE(puller.IsBlocking()); + + std::this_thread::sleep_for(2s); + std::vector numbers; + bool end = false; + const auto t0 = std::chrono::steady_clock::now(); + while (!end && std::chrono::steady_clock::now() - t0 < 60s) { + const auto m = puller.PollImage(10ms); + if (!m) + continue; + if (m->cbor->data_message) + numbers.push_back(m->cbor->data_message->number); + end = m->cbor->end_message.has_value(); + } + CHECK(end); + puller.Stop(); + CHECK(puller.GetDroppedImages() == 0); + CHECK(puller.GetSlotWaitTime_s() > 0.5); + REQUIRE(numbers.size() == 20); + for (size_t i = 0; i < numbers.size(); i++) + CHECK(numbers[i] == static_cast(i)); +} + +// Paced: the images are taken from the card at most at the rate given +TEST_CASE("FPGAImagePuller_Paced", "[FPGAImagePuller]") { + auto x = Base(DetJF(1), 10, 1); + x.Conversion(); + x.Compression(CompressionAlgorithm::BSHUF_LZ4); + + auto devices = Devices(x); + Logger logger("FPGAImagePuller_Paced"); + PixelMask mask(x); + const JFCalibration calib = Calibration(x); + const auto t0 = std::chrono::steady_clock::now(); + FPGAImagePuller puller(x, mask, &calib, devices, logger, 2, 16, true, 10.0); + + size_t images = 0; + bool end = false; + while (!end && std::chrono::steady_clock::now() - t0 < 60s) { + const auto m = puller.PollImage(10ms); + if (!m) + continue; + if (m->cbor->data_message) + images++; + end = m->cbor->end_message.has_value(); + } + puller.Stop(); + CHECK(images == 10); + // Image 9 is taken 0.9 s after the start at the earliest + CHECK(std::chrono::steady_clock::now() - t0 > 900ms); +} + // The same behind Lite: a writer that takes its time keeps Lite's only thread, and the drops reach the statistics. TEST_CASE("FPGAImagePuller_SlowConsumer_Receiver", "[FPGAImagePuller]") { auto x = Base(DetJF(1), 24, 1); diff --git a/tools/jfjoch_fpga_stills_test.cpp b/tools/jfjoch_fpga_stills_test.cpp index 2db0da20a..11843b7bd 100644 --- a/tools/jfjoch_fpga_stills_test.cpp +++ b/tools/jfjoch_fpga_stills_test.cpp @@ -9,6 +9,7 @@ #include #include +#include #include #include "../acquisition_device/PCIExpressDevice.h" @@ -35,8 +36,10 @@ void print_usage(Logger &logger) { logger.Info(" -C Unit cell (default: the file's)"); logger.Info(" -X Indexing (auto|fft|fftw|ffbidx), auto is default"); logger.Info(" -t Indexing thread pool size (default: 4)"); + logger.Info(" -r Rates the source is paced at, one collection each (default: 0 = as fast as it goes)"); logger.Info(" -p FPGAImagePuller slots (default 128)"); - logger.Info(" -F JFJochReceiverFPGA's own live stills instead of FPGAImagePuller"); + logger.Info(" -F JFJochReceiverFPGA's own live stills instead of FPGAImagePuller (not blocking: frames"); + logger.Info(" past what its analysis holds are lost)"); logger.Info(" -K{} Mock of the card instead of /dev/jfjoch* (optional: its generator memory, default 64 MiB ="); logger.Info(" 128 module frames)"); } @@ -82,7 +85,7 @@ int64_t GeneratorImages(AcquisitionDeviceGroup &aq_devices, const DiffractionExp bool RunDataset(Logger &logger, AcquisitionDeviceGroup &aq_devices, const std::string &file, std::optional nimages, uint16_t nstreams, uint16_t nthreads, size_t send_buffer_size_MiB, const IndexingSettings &indexing, const std::optional &cell, size_t puller_slots, - bool fpga_receiver) { + bool fpga_receiver, const std::vector &rates) { RegisterHDF5Filter(); JFJochHDF5Reader reader; reader.ReadFile(file); @@ -133,16 +136,12 @@ bool RunDataset(Logger &logger, AcquisitionDeviceGroup &aq_devices, const std::s logger.Debug(" module {}: pixel 0 at ({}, {}), fast step {}, slow step {}", m, x.GetPixel0OfModuleConv(m) % x.GetXPixelsNum(), x.GetPixel0OfModuleConv(m) / x.GetXPixelsNum(), x.GetModuleFastDirectionStep(m), x.GetModuleSlowDirectionStep(m)); - logger.Info("Mode: {}, rugnux live stills", fpga_receiver ? "JFJochReceiverFPGA" - : fmt::format("FPGAImagePuller ({} slots)", puller_slots)); NonePusher pusher; JFJochReceiverService service(aq_devices, logger, pusher, send_buffer_size_MiB); service.NumThreads(nthreads); service.Indexing(x.GetIndexingSettings()); service.RugnuxLive(true, nullptr, 4, 60); - service.UseFPGAImagePuller(fpga_receiver ? FPGAImagePullerUse::Never : FPGAImagePullerUse::RugnuxLive, - puller_slots); // Error, gap and beam-stop pixels of the reader become error pixels of the module frame std::vector frame(x.GetModulesNum() * RAW_MODULE_SIZE); @@ -155,60 +154,106 @@ bool RunDataset(Logger &logger, AcquisitionDeviceGroup &aq_devices, const std::s service.LoadInternalGeneratorImage(x, frame_u16, i); } - rusage usage_start{}; - getrusage(RUSAGE_SELF, &usage_start); - const auto wall_start = std::chrono::steady_clock::now(); + struct Row { + double rate_hz, delivered_hz, blocked, sustained_hz, after_prepass_hz, indexing_rate; + uint64_t images, dropped; + }; + std::vector rows; + bool ok = true; - service.Start(x, mask, nullptr); - const auto output = service.Stop(); - const auto live = service.GetRugnuxStatus(); + for (const double rate: rates) { + // Blocking at source: the puller waits for a free slot and the receiver for room in the image buffer, + // the cards hold their frames and their generators stall. JFJochReceiverFPGA's live stills cannot block. + service.UseFPGAImagePuller(fpga_receiver ? FPGAImagePullerUse::Never : FPGAImagePullerUse::RugnuxLive, + puller_slots, true, rate); + logger.Info(""); + logger.Info("=== {}, {} ===", fpga_receiver ? "JFJochReceiverFPGA (not blocking)" + : fmt::format("FPGAImagePuller ({} slots, blocking)", puller_slots), + (rate > 0) ? fmt::format("source paced at {:.1f} Hz", rate) : std::string("source as fast as it goes")); - const double wall_time = std::chrono::duration(std::chrono::steady_clock::now() - wall_start).count(); - rusage usage_end{}; - getrusage(RUSAGE_SELF, &usage_end); - auto seconds = [](const timeval &t) { return static_cast(t.tv_sec) + static_cast(t.tv_usec) / 1e6; }; - const double cpu_time = seconds(usage_end.ru_utime) - seconds(usage_start.ru_utime) - + seconds(usage_end.ru_stime) - seconds(usage_start.ru_stime); - const double receiving_time = static_cast(output.end_time_ms - output.start_time_ms) / 1000.0; + rusage usage_start{}; + getrusage(RUSAGE_SELF, &usage_start); + const auto wall_start = std::chrono::steady_clock::now(); - int64_t spots = 0, spot_images = 0; - for (const auto &e: output.scan_result.images) - if (e.spot_count) { - spots += e.spot_count.value(); - spot_images++; + service.Start(x, mask, nullptr); + const auto output = service.Stop(); + const auto live = service.GetRugnuxStatus(); + + const double wall_time = std::chrono::duration(std::chrono::steady_clock::now() - wall_start).count(); + rusage usage_end{}; + getrusage(RUSAGE_SELF, &usage_end); + auto seconds = [](const timeval &t) { return static_cast(t.tv_sec) + static_cast(t.tv_usec) / 1e6; }; + const double cpu_time = seconds(usage_end.ru_utime) - seconds(usage_start.ru_utime) + + seconds(usage_end.ru_stime) - seconds(usage_start.ru_stime); + + int64_t spots = 0, spot_images = 0; + for (const auto &e: output.scan_result.images) + if (e.spot_count) { + spots += e.spot_count.value(); + spot_images++; + } + + // From the first image to the last one into the receiver; the source was blocked for the time the module + // threads waited for a free slot, as a fraction of that span (mean over the modules) + const double delivery_s = live.last_image_s.value_or(0); + const double delivered_hz = (delivery_s > 0) ? static_cast(output.status.images_collected - 1) / delivery_s : 0; + const double blocked = (delivery_s > 0) ? service.GetFPGAImagePullerSlotWaitTime_s() / (delivery_s * x.GetModulesNum()) : 0; + + logger.Info("Images expected {} collected {} sent {} dropped {} efficiency {:.4f}", + x.GetImageNum(), output.status.images_collected, output.status.images_sent, + output.status.images_dropped, output.efficiency); + logger.Info("Delivered {:.1f} Hz (first to last image {:.2f} s), source blocked {:.1f}% of it", + delivered_hz, delivery_s, 100.0 * blocked); + logger.Info("Sustained {:.1f} Hz (images / wall time {:.2f} s, start to analysis done) CPU {:.1f} s = {:.1f} cores", + static_cast(output.status.images_collected) / wall_time, wall_time, cpu_time, + cpu_time / wall_time); + // The card's own count of the cycles (200 MHz) it waited for a host buffer, i.e. was held by the host + for (int i = 0; i < x.GetDataStreamsNum(); i++) { + const auto status = aq_devices[i].GetDataCollectionStatus(); + logger.Info("Card {}: waited for host buffers {:.2f} s ({:.1f}% of the delivery), stalls before HBM {} cycles", + i, status.pipeline_stalls_host / 200e6, + (delivery_s > 0) ? 100.0 * status.pipeline_stalls_host / 200e6 / delivery_s : 0.0, + status.pipeline_stalls_hbm); } + logger.Info("Indexing rate {:.3f} spots per image {:.1f}", output.status.indexing_rate.value_or(0), + static_cast(spots) / std::max(1, spot_images)); + logger.Info("Per-image time (mean; microseconds): preprocess {:.0f} spot finding {:.0f} indexing {:.0f} " + "refinement {:.0f} integration {:.0f} total {:.0f}", + output.processing_time.preprocessing * 1e6, output.processing_time.spot_finding * 1e6, + output.processing_time.indexing * 1e6, output.processing_time.refinement * 1e6, + output.processing_time.integration * 1e6, output.processing_time.processing * 1e6); + double after_prepass_hz = 0; + if (live.stills) { + const auto &st = *live.stills; + after_prepass_hz = st.analysis_rate_hz.value_or(0); + logger.Info("Pre-pass {:.2f} s: beam {:.2f} {:.2f} px (file {:.2f} {:.2f}), distance {:.2f} mm (file {:.2f})", + st.prepass_s.value_or(0), st.beam_x_pxl.value_or(NAN), st.beam_y_pxl.value_or(NAN), + st.file_beam_x_pxl, st.file_beam_y_pxl, st.distance_mm.value_or(NAN), st.file_distance_mm); + logger.Info("Analysed {} indexed {} analysis rate after the pre-pass {:.1f} Hz", st.images_analysed, + st.images_indexed, after_prepass_hz); + } + logger.Info("Rugnux: {} {} last image at {:.2f} s, done {:.2f} s after it", live.verdict, live.message, + live.last_image_s.value_or(NAN), live.last_image_to_written_s.value_or(NAN)); + for (const auto &step: live.steps) + logger.Info(" step {:.2f} s + {:.2f} s {}", step.started_s, step.duration_s.value_or(NAN), step.title); + + rows.push_back(Row{.rate_hz = rate, .delivered_hz = delivered_hz, .blocked = blocked, + .sustained_hz = static_cast(output.status.images_collected) / wall_time, + .after_prepass_hz = after_prepass_hz, + .indexing_rate = output.status.indexing_rate.value_or(0), + .images = output.status.images_collected, .dropped = output.status.images_dropped}); + ok = ok && (output.efficiency > 0) && (live.state == RugnuxLiveState::Done); + } logger.Info(""); - logger.Info("=== Summary ==="); - logger.Info("Images expected {} collected {} sent {} dropped by the puller {} efficiency {:.4f}", - x.GetImageNum(), output.status.images_collected, output.status.images_sent, - output.status.images_dropped, output.efficiency); - logger.Info("Receiving time {:.3f} s frame rate {:.1f} Hz wall time {:.3f} s CPU {:.1f} s = {:.1f} cores", - receiving_time, static_cast(x.GetImageNum()) / receiving_time, wall_time, cpu_time, - cpu_time / wall_time); - logger.Info("Indexing rate {:.3f} spots per image {:.1f}", output.status.indexing_rate.value_or(0), - static_cast(spots) / std::max(1, spot_images)); - logger.Info("Per-image time (mean; microseconds): preprocess {:.0f} spot finding {:.0f} indexing {:.0f} " - "refinement {:.0f} integration {:.0f} total {:.0f}", - output.processing_time.preprocessing * 1e6, output.processing_time.spot_finding * 1e6, - output.processing_time.indexing * 1e6, output.processing_time.refinement * 1e6, - output.processing_time.integration * 1e6, output.processing_time.processing * 1e6); - if (live.stills) { - const auto &st = *live.stills; - logger.Info("Pre-pass {:.2f} s: beam {:.2f} {:.2f} px (file {:.2f} {:.2f}), distance {:.2f} mm (file {:.2f})", - st.prepass_s.value_or(0), st.beam_x_pxl.value_or(NAN), st.beam_y_pxl.value_or(NAN), - st.file_beam_x_pxl, st.file_beam_y_pxl, st.distance_mm.value_or(NAN), st.file_distance_mm); - logger.Info("Analysed {} indexed {} analysis rate {:.1f} Hz", st.images_analysed, st.images_indexed, - st.analysis_rate_hz.value_or(0)); - } - logger.Info("Rugnux: {} {} space group {} last image at {:.2f} s, done {:.2f} s after it", - live.verdict, live.message, live.space_group, live.last_image_s.value_or(NAN), - live.last_image_to_written_s.value_or(NAN)); - for (const auto &step: live.steps) - logger.Info(" step {:.2f} s + {:.2f} s {}", step.started_s, step.duration_s.value_or(NAN), step.title); - logger.Info("Images repeat ({} distinct): the merge and its statistics are not a measure of the data", generator_images); - - return (output.efficiency > 0) && (live.state == RugnuxLiveState::Done); + logger.Info("=== Rates ({} images, {} distinct: images repeat, the merge and its statistics are not a measure of the data) ===", + x.GetImageNum(), generator_images); + logger.Info(" source Hz delivered Hz blocked sustained Hz after pre-pass Hz indexing images dropped"); + for (const auto &r: rows) + logger.Info(" {:>9} {:>12.1f} {:>6.1f}% {:>12.1f} {:>17.1f} {:>8.3f} {:>6} {:>7}", + (r.rate_hz > 0) ? fmt::format("{:.1f}", r.rate_hz) : std::string("max"), r.delivered_hz, + 100.0 * r.blocked, r.sustained_hz, r.after_prepass_hz, r.indexing_rate, r.images, r.dropped); + return ok; } int main(int argc, char **argv) { @@ -228,9 +273,10 @@ int main(int argc, char **argv) { bool fpga_receiver = false; std::optional mock_card_MiB; bool verbose = false; + std::vector rates = {0}; int opt; - while ((opt = getopt(argc, argv, "vi:s:N:B:C:X:t:p:FK::")) != -1) { + while ((opt = getopt(argc, argv, "vi:s:N:B:C:X:t:r:p:FK::")) != -1) { switch (opt) { case 'v': verbose = true; @@ -269,6 +315,14 @@ int main(int argc, char **argv) { case 't': indexing_threads = atol(optarg); break; + case 'r': { + rates.clear(); + std::stringstream list(optarg); + std::string rate; + while (std::getline(list, rate, ',')) + rates.push_back(atof(rate.c_str())); + break; + } case 'p': puller_slots = atol(optarg); break; @@ -310,7 +364,7 @@ int main(int argc, char **argv) { bool ret = false; try { ret = RunDataset(logger, aq_devices, argv[optind], nimages, nstreams, nthreads, send_buffer_size_MiB, - i_settings, cell, puller_slots, fpga_receiver); + i_settings, cell, puller_slots, fpga_receiver, rates); } catch (std::exception &e) { logger.Error(e.what()); } From 9f38cffddaa19cd46e71c8e9c62dbe015effcc65 Mon Sep 17 00:00:00 2001 From: Filip Leonarski Date: Wed, 18 Nov 2026 09:59:14 +0100 Subject: [PATCH 07/41] docs/TOOLS.md: rugnux -e is the end image, exclusive Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01UqXYdHHZ4cogS1mrGUtfN7 --- docs/TOOLS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/TOOLS.md b/docs/TOOLS.md index 14e9debec..56cfe734f 100644 --- a/docs/TOOLS.md +++ b/docs/TOOLS.md @@ -122,7 +122,7 @@ jfjoch_fpga_stills_test [-i ] [-s ] [-N ] [-B ] [-C loaded) instead of `/dev/jfjoch*`, so the program runs without a card; the optional value is the mock's generator memory in MiB (default 64 MiB = 128 module frames). - To compare with the offline analysis of the same images, run it with `-i` equal to the number of - distinct images it reports (no repeats) and `rugnux --force-still -e ` or + distinct images it reports (no repeats) and `rugnux --force-still -e ` or `jfjoch_stills_gpu_replay -n ` on the same file. ### jfjoch_lite_perf_test From 3ac1fd657f358ef9221cea25840d980df006e93e Mon Sep 17 00:00:00 2001 From: Filip Leonarski Date: Wed, 18 Nov 2026 10:09:53 +0100 Subject: [PATCH 08/41] CMake: cuFFT linked statically wherever the toolkit has the static library The server build linked libcufft.so, so any executable copied to another machine needed the CUDA toolkit library beside it; only the portable builds linked libcufft_static.a. Now every build does where CUDA::cufft_static exists (Linux); Windows, which has none, keeps the DLL as before. libcufft_static.a needs a device-link step in every executable that links it. The four per-target CUDA_RESOLVE_DEVICE_SYMBOLS settings (rugnux, jfjoch_viewer, jfjoch_portable_test, rugnux_refine_test) become one pass at the end of the top-level CMakeLists over the executables and shared libraries of the source tree (fetched dependencies left alone). Executables grow by about 290 MB (rugnux 193 -> 486 MB, jfjoch_broker 488 MB, jfjoch_fpga_stills_test 484 MB); ldd no longer lists libcufft. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01UqXYdHHZ4cogS1mrGUtfN7 --- CMakeLists.txt | 26 +++++++++++++++++++ image_analysis/geom_refinement/CMakeLists.txt | 2 +- image_analysis/indexing/CMakeLists.txt | 8 +++--- rugnux/CMakeLists.txt | 8 ------ tests/CMakeLists.txt | 4 --- tools/CMakeLists.txt | 4 --- viewer/CMakeLists.txt | 8 ------ 7 files changed, 31 insertions(+), 29 deletions(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index 88e03e81b..4626a2392 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -656,6 +656,32 @@ IF (NOT JFJOCH_WRITER_ONLY AND NOT JFJOCH_PORTABLE_ONLY) INSTALL(DIRECTORY ${CMAKE_SOURCE_DIR}/frontend/dist/ DESTINATION share/jfjoch/frontend COMPONENT jfjoch ) ENDIF() +# libcufft_static.a carries a relocatable-device-code object (separate_callback.o), so an executable +# linking it needs a CUDA device-link step -- without it the host link fails on an undefined +# __cudaRegisterLinkedBinary_* symbol. CUDA 13 no longer ships libcufft_static_nocallback.a, which +# used to be the way around it. CUDA_RESOLVE_DEVICE_SYMBOLS makes CMake emit that step while leaving +# the host link driver alone, so the -march/-flto flags CI passes still apply. Set on every executable +# and shared library of this source tree, as nearly all of them link the image analysis. +FUNCTION(JFJOCH_RESOLVE_DEVICE_SYMBOLS dir) + GET_PROPERTY(_targets DIRECTORY ${dir} PROPERTY BUILDSYSTEM_TARGETS) + FOREACH(_target IN LISTS _targets) + GET_TARGET_PROPERTY(_type ${_target} TYPE) + IF (_type MATCHES "EXECUTABLE|SHARED_LIBRARY|MODULE_LIBRARY") + SET_TARGET_PROPERTIES(${_target} PROPERTIES CUDA_RESOLVE_DEVICE_SYMBOLS ON) + ENDIF() + ENDFOREACH() + GET_PROPERTY(_subdirs DIRECTORY ${dir} PROPERTY SUBDIRECTORIES) + FOREACH(_subdir IN LISTS _subdirs) + STRING(FIND "${_subdir}" "${CMAKE_SOURCE_DIR}/" _position) + IF (_position EQUAL 0) # not the fetched dependencies + JFJOCH_RESOLVE_DEVICE_SYMBOLS(${_subdir}) + ENDIF() + ENDFOREACH() +ENDFUNCTION() +IF (JFJOCH_CUDA_AVAILABLE AND TARGET CUDA::cufft_static) + JFJOCH_RESOLVE_DEVICE_SYMBOLS(${CMAKE_SOURCE_DIR}) +ENDIF() + # Windows has no static cuFFT (the toolkit ships no cufft_static.lib), so there the indexer links # the import library and the self-contained products must carry the DLL beside the executable -- # the same idea the Linux builds no longer need, since they link libcufft_static.a. CUDA 13 keeps diff --git a/image_analysis/geom_refinement/CMakeLists.txt b/image_analysis/geom_refinement/CMakeLists.txt index a82fee507..74659539b 100644 --- a/image_analysis/geom_refinement/CMakeLists.txt +++ b/image_analysis/geom_refinement/CMakeLists.txt @@ -47,7 +47,7 @@ IF (JFJOCH_CUDA_AVAILABLE) BeamCenterBackgroundGPU.cu BeamCenterBackgroundGPU.h) # Same static/dynamic cuFFT choice as the FFT indexer, and for the same reasons - see the long # note in image_analysis/indexing/CMakeLists.txt. - IF (JFJOCH_PORTABLE_ONLY AND TARGET CUDA::cufft_static) + IF (TARGET CUDA::cufft_static) TARGET_LINK_LIBRARIES(JFJochGeomRefinement CUDA::cufft_static) ELSE() TARGET_LINK_LIBRARIES(JFJochGeomRefinement CUDA::cufft) diff --git a/image_analysis/indexing/CMakeLists.txt b/image_analysis/indexing/CMakeLists.txt index e7d787197..66f005b10 100644 --- a/image_analysis/indexing/CMakeLists.txt +++ b/image_analysis/indexing/CMakeLists.txt @@ -51,10 +51,10 @@ IF (JFJOCH_CUDA_AVAILABLE) # and the dynamic library is the only option; the top-level CMakeLists installs the DLL beside # the executable for the self-contained builds. Test the target rather than the platform, so a # toolkit that gains or loses the static library is handled without another special case. - # Both halves matter: the server build keeps the shared library (its .deb/.rpm take CUDA from the - # distro, and every executable there -- broker, tests, tools -- would otherwise need the device - # link below), and Windows has no static cuFFT to link even for the portable products. - IF (JFJOCH_PORTABLE_ONLY AND TARGET CUDA::cufft_static) + # The server build links it statically too, so its executables (broker, tools copied to another + # machine) need no CUDA toolkit library; the top-level CMakeLists gives every executable the device + # link this needs. + IF (TARGET CUDA::cufft_static) TARGET_LINK_LIBRARIES(JFJochIndexing fast_indexer_static CUDA::cufft_static) ELSE() TARGET_LINK_LIBRARIES(JFJochIndexing fast_indexer_static CUDA::cufft) diff --git a/rugnux/CMakeLists.txt b/rugnux/CMakeLists.txt index 12db3d061..132d93764 100644 --- a/rugnux/CMakeLists.txt +++ b/rugnux/CMakeLists.txt @@ -66,14 +66,6 @@ IF(APPLE AND JFJOCH_MACOS_SIGNING_IDENTITY) COMPONENT rugnux) ENDIF() -# libcufft_static.a carries a relocatable-device-code object (separate_callback.o), so an executable -# linking it needs a CUDA device-link step -- without it the host link fails on an undefined -# __cudaRegisterLinkedBinary_* symbol. CUDA 13 no longer ships libcufft_static_nocallback.a, which -# used to be the way around it. CUDA_RESOLVE_DEVICE_SYMBOLS makes CMake emit that step while leaving -# the host link driver alone, so the -march/-flto flags CI passes still apply. -IF (JFJOCH_PORTABLE_ONLY AND JFJOCH_CUDA_AVAILABLE AND TARGET CUDA::cufft_static) - SET_TARGET_PROPERTIES(rugnux PROPERTIES CUDA_RESOLVE_DEVICE_SYMBOLS ON) -ENDIF() # On Windows this CLI gets getopt/getopt_long from the vendored wingetopt shim (libc has none). diff --git a/tests/CMakeLists.txt b/tests/CMakeLists.txt index f30cb28c6..ed7af1f68 100644 --- a/tests/CMakeLists.txt +++ b/tests/CMakeLists.txt @@ -47,10 +47,6 @@ ADD_EXECUTABLE(jfjoch_portable_test EXCLUDE_FROM_ALL target_link_libraries(jfjoch_portable_test Catch2WithMain JFJochRugnux JFJochReader JFJochImageAnalysis JFJochWriter JFJochAPIConvert JFJochCommon) target_include_directories(jfjoch_portable_test PRIVATE .) -# Same device-link step as rugnux (see rugnux/CMakeLists.txt): a portable CUDA build links cuFFT statically. -IF (JFJOCH_PORTABLE_ONLY AND JFJOCH_CUDA_AVAILABLE AND TARGET CUDA::cufft_static) - SET_TARGET_PROPERTIES(jfjoch_portable_test PROPERTIES CUDA_RESOLVE_DEVICE_SYMBOLS ON) -ENDIF() # The CPU vs GPU test of the fast-feedback indexer reads the library's own test spot lists IF (JFJOCH_CUDA_AVAILABLE) diff --git a/tools/CMakeLists.txt b/tools/CMakeLists.txt index 9fdf2e2a9..74d302a1c 100644 --- a/tools/CMakeLists.txt +++ b/tools/CMakeLists.txt @@ -18,10 +18,6 @@ TARGET_LINK_LIBRARIES(jfjoch_extract_hkl JFJochReader) # measuring the refinement on battery outputs without processing anything again. ADD_EXECUTABLE(rugnux_refine_test rugnux_refine_test.cpp) TARGET_LINK_LIBRARIES(rugnux_refine_test JFJochStructureRefinement JFJochCommon gemmi) -# Same device-link step as rugnux (see rugnux/CMakeLists.txt): a portable CUDA build links cuFFT statically. -IF (JFJOCH_PORTABLE_ONLY AND JFJOCH_CUDA_AVAILABLE AND TARGET CUDA::cufft_static) - SET_TARGET_PROPERTIES(rugnux_refine_test PROPERTIES CUDA_RESOLVE_DEVICE_SYMBOLS ON) -ENDIF() # In-place re-compress /entry/data/data of a _data file from bitshuffle/LZ4 to bitshuffle/zstd. ADD_EXECUTABLE(jfjoch_recompress jfjoch_recompress.cpp) diff --git a/viewer/CMakeLists.txt b/viewer/CMakeLists.txt index 0345b7587..ec62a3b68 100644 --- a/viewer/CMakeLists.txt +++ b/viewer/CMakeLists.txt @@ -184,14 +184,6 @@ IF(APPLE) PATTERN "COLLECT.sh" EXCLUDE) ENDIF() -# libcufft_static.a carries a relocatable-device-code object (separate_callback.o), so an executable -# linking it needs a CUDA device-link step -- without it the host link fails on an undefined -# __cudaRegisterLinkedBinary_* symbol. CUDA 13 no longer ships libcufft_static_nocallback.a, which -# used to be the way around it. CUDA_RESOLVE_DEVICE_SYMBOLS makes CMake emit that step while leaving -# the host link driver alone, so the -march/-flto flags CI passes still apply. -IF (JFJOCH_PORTABLE_ONLY AND JFJOCH_CUDA_AVAILABLE AND TARGET CUDA::cufft_static) - SET_TARGET_PROPERTIES(jfjoch_viewer PROPERTIES CUDA_RESOLVE_DEVICE_SYMBOLS ON) -ENDIF() IF(JFJOCH_VIEWER_DBUS) From efb676520734e382c80517011d1799fd6581afc5 Mon Sep 17 00:00:00 2001 From: Filip Leonarski Date: Wed, 18 Nov 2026 10:09:53 +0100 Subject: [PATCH 09/41] jfjoch_fpga_stills_test: -d (not blocking, as the broker), -v card progress -d runs the puller as the broker does, dropping what the host has no room for, to compare with the default blocking run. -v logs each card's slowest and fastest module frame every 0.5 s. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01UqXYdHHZ4cogS1mrGUtfN7 --- tools/jfjoch_fpga_stills_test.cpp | 35 +++++++++++++++++++++++++------ 1 file changed, 29 insertions(+), 6 deletions(-) diff --git a/tools/jfjoch_fpga_stills_test.cpp b/tools/jfjoch_fpga_stills_test.cpp index 11843b7bd..09e0eacd6 100644 --- a/tools/jfjoch_fpga_stills_test.cpp +++ b/tools/jfjoch_fpga_stills_test.cpp @@ -7,9 +7,11 @@ // The generator cycles through the images its memory holds, so images repeat: throughput, latency and indexing rate // are meaningful, the merge and its statistics are not. +#include #include #include #include +#include #include #include "../acquisition_device/PCIExpressDevice.h" @@ -28,7 +30,7 @@ void print_usage(Logger &logger) { logger.Info("loaded into the cards' internal generators, which cycle through them: images repeat, so throughput, latency"); logger.Info("and indexing rate are meaningful, the merge and its statistics are not. See docs/TOOLS.md."); logger.Info("Options:"); - logger.Info(" -v Verbose"); + logger.Info(" -v Verbose, with each card's progress every 0.5 s"); logger.Info(" -i Images in the run (default: as many as the file has)"); logger.Info(" -s Number of data streams (cards)"); logger.Info(" -N Number of image processing threads (default 64)"); @@ -38,6 +40,7 @@ void print_usage(Logger &logger) { logger.Info(" -t Indexing thread pool size (default: 4)"); logger.Info(" -r Rates the source is paced at, one collection each (default: 0 = as fast as it goes)"); logger.Info(" -p FPGAImagePuller slots (default 128)"); + logger.Info(" -d Not blocking, as the broker runs: images the host has no room for are dropped"); logger.Info(" -F JFJochReceiverFPGA's own live stills instead of FPGAImagePuller (not blocking: frames"); logger.Info(" past what its analysis holds are lost)"); logger.Info(" -K{} Mock of the card instead of /dev/jfjoch* (optional: its generator memory, default 64 MiB ="); @@ -85,7 +88,7 @@ int64_t GeneratorImages(AcquisitionDeviceGroup &aq_devices, const DiffractionExp bool RunDataset(Logger &logger, AcquisitionDeviceGroup &aq_devices, const std::string &file, std::optional nimages, uint16_t nstreams, uint16_t nthreads, size_t send_buffer_size_MiB, const IndexingSettings &indexing, const std::optional &cell, size_t puller_slots, - bool fpga_receiver, const std::vector &rates) { + bool fpga_receiver, const std::vector &rates, bool dropping) { RegisterHDF5Filter(); JFJochHDF5Reader reader; reader.ReadFile(file); @@ -165,10 +168,11 @@ bool RunDataset(Logger &logger, AcquisitionDeviceGroup &aq_devices, const std::s // Blocking at source: the puller waits for a free slot and the receiver for room in the image buffer, // the cards hold their frames and their generators stall. JFJochReceiverFPGA's live stills cannot block. service.UseFPGAImagePuller(fpga_receiver ? FPGAImagePullerUse::Never : FPGAImagePullerUse::RugnuxLive, - puller_slots, true, rate); + puller_slots, !dropping, rate); logger.Info(""); logger.Info("=== {}, {} ===", fpga_receiver ? "JFJochReceiverFPGA (not blocking)" - : fmt::format("FPGAImagePuller ({} slots, blocking)", puller_slots), + : fmt::format("FPGAImagePuller ({} slots, {})", puller_slots, + dropping ? "dropping" : "blocking"), (rate > 0) ? fmt::format("source paced at {:.1f} Hz", rate) : std::string("source as fast as it goes")); rusage usage_start{}; @@ -176,7 +180,22 @@ bool RunDataset(Logger &logger, AcquisitionDeviceGroup &aq_devices, const std::s const auto wall_start = std::chrono::steady_clock::now(); service.Start(x, mask, nullptr); + // -v: each card's progress, the frames of its fastest and slowest module written to the host + std::atomic running = true; + std::thread progress([&] { + while (running) { + std::this_thread::sleep_for(std::chrono::milliseconds(500)); + std::string line; + for (int i = 0; i < x.GetDataStreamsNum(); i++) + line += fmt::format(" card {}: {} .. {}", i, aq_devices[i].Counters().GetSlowestFrameNumber(), + aq_devices[i].Counters().GetFastestFrameNumber()); + logger.Debug("{:.1f} s{}", std::chrono::duration(std::chrono::steady_clock::now() + - wall_start).count(), line); + } + }); const auto output = service.Stop(); + running = false; + progress.join(); const auto live = service.GetRugnuxStatus(); const double wall_time = std::chrono::duration(std::chrono::steady_clock::now() - wall_start).count(); @@ -274,9 +293,10 @@ int main(int argc, char **argv) { std::optional mock_card_MiB; bool verbose = false; std::vector rates = {0}; + bool dropping = false; int opt; - while ((opt = getopt(argc, argv, "vi:s:N:B:C:X:t:r:p:FK::")) != -1) { + while ((opt = getopt(argc, argv, "vi:s:N:B:C:X:t:r:p:dFK::")) != -1) { switch (opt) { case 'v': verbose = true; @@ -329,6 +349,9 @@ int main(int argc, char **argv) { case 'F': fpga_receiver = true; break; + case 'd': + dropping = true; + break; case 'K': mock_card_MiB = (optarg != nullptr) ? atol(optarg) : 64; break; @@ -364,7 +387,7 @@ int main(int argc, char **argv) { bool ret = false; try { ret = RunDataset(logger, aq_devices, argv[optind], nimages, nstreams, nthreads, send_buffer_size_MiB, - i_settings, cell, puller_slots, fpga_receiver, rates); + i_settings, cell, puller_slots, fpga_receiver, rates, dropping); } catch (std::exception &e) { logger.Error(e.what()); } From 3a5391dd65152cf7fabf0f593239f27a044d655c Mon Sep 17 00:00:00 2001 From: Filip Leonarski Date: Wed, 18 Nov 2026 10:20:23 +0100 Subject: [PATCH 10/41] FPGAImagePuller: a module behind another card waits as long as the slots hold A module was given up for a frame once ANY card was MissingAfterFrames (52) frames further on. The cards run on their own, so a card a little behind lost whole modules from every image: on the mock, 9M on 2 and 4 cards not blocking, the cards drift 50-500 frames apart (each mock card is two CPU threads; none of them ever waited for host buffers, so the drift is the cards' own speed, not the host) and the efficiency was 0.44-0.61. Now a module is missing when its OWN card is MissingAfterFrames further on, as the device itself counts, and behind another card only once that card is max_slots ahead - past that, its images would be dropped for want of a slot anyway. A dead card is still noticed, after max_slots frames. Mock, 9M, 1500 images, not blocking: 2 cards 0.905 (drift up to ~120), 4 cards with 512 slots 0.978 (drift ~380), 4 cards with 128 slots 0.487 (drift ~500, now whole images dropped for want of a slot rather than modules missing). Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01UqXYdHHZ4cogS1mrGUtfN7 --- receiver/FPGAImagePuller.cpp | 3 ++- receiver/FPGAImagePuller.h | 4 +++- 2 files changed, 5 insertions(+), 2 deletions(-) diff --git a/receiver/FPGAImagePuller.cpp b/receiver/FPGAImagePuller.cpp index 26eacc4c0..5d0d884a4 100644 --- a/receiver/FPGAImagePuller.cpp +++ b/receiver/FPGAImagePuller.cpp @@ -147,7 +147,8 @@ void FPGAImagePuller::WaitForFrame(uint16_t data_stream, uint16_t module_number, // A frame is complete once the module is two further on, as in JFJochReceiverFPGA if ((static_cast(counters.GetCurrFrameNumber(module_number)) >= frame + 2) || counters.IsAcquisitionFinished() || failed - || (!blocking && (FastestFrame() >= frame + 2 + MissingAfterFrames))) + || (!blocking && (static_cast(counters.GetFastestFrameNumber()) >= frame + 2 + MissingAfterFrames)) + || (!blocking && (FastestFrame() >= frame + 2 + static_cast(max_slots)))) return; std::this_thread::sleep_for(std::chrono::milliseconds(1)); } diff --git a/receiver/FPGAImagePuller.h b/receiver/FPGAImagePuller.h index 844a839f5..d5d90a16e 100644 --- a/receiver/FPGAImagePuller.h +++ b/receiver/FPGAImagePuller.h @@ -24,7 +24,9 @@ class FPGAImagePuller : public ImagePuller { public: static constexpr size_t DefaultSlots = 128; - // A module this far behind the fastest one is taken as missing from that frame, as the device itself does + // A module this far behind the fastest one of its card is taken as missing from that frame, as the device itself + // does. Behind another card it is waited for as long as the slots can hold the images started meanwhile: the + // cards run on their own and one can be ahead, but past max_slots its images would be dropped anyway. static constexpr int64_t MissingAfterFrames = AcquisitionCounters::ThresholdFramesLost + 2; private: struct Slot { From 17bfca6a22a45abcf7e4bb7eca1ce109e06f201d Mon Sep 17 00:00:00 2001 From: Filip Leonarski Date: Wed, 18 Nov 2026 10:57:22 +0100 Subject: [PATCH 11/41] Live stills: frames indexed on the pre-pass's refined cell and spot budget, as offline The pre-pass refines the cell beside the distance (their scales trade), and offline indexes every frame on that refined cell with up to 1000 spots. Live kept the stated cell at the refined distance (off in scale by as much as the distance moved, 1.7% on one 9M set) and the broker's 250-spot cap (a third short of a 9M frame's ~380 spots). Both now come from the pre-pass result; the start message keeps the stated cell, and the merge keeps it as the given cell. Replay on the first N frames (live before -> after, offline rugnux on the same frames): 9M 100 frames 0.99 -> 1.00 (offline 0.99), merge CC1/2 0.758 -> 0.798; 9M 30 frames 0.967 -> 1.00; 4M 100 frames 1.00 -> 1.00 (offline 1.00); 8M 200 frames 0.320 -> 0.325 (offline with the file's space group 0.320). Per-image analysis +10% on 9M (16.0 -> 17.6 ms, more spots). The 8M gap reported (live 0.35 vs offline 0.56) was the comparison: the file carries a space group, which live takes from it and offline only with -S. Offline with -S gives 0.349 = live; without it, offline indexes 13-14 more frames of 6-10 spots out of ~40, and merges worse (CC1/2 0.10 vs 0.20). jfjoch_stills_gpu_replay: -p spots per image; per-frame _images.tsv and _spots.tsv to compare frame by frame with an offline _process.h5. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01UqXYdHHZ4cogS1mrGUtfN7 --- receiver/JFJochReceiverRugnuxStills.cpp | 2 ++ receiver/StillsGPUAnalysis.cpp | 9 ++++++++- receiver/StillsPrePass.cpp | 2 ++ receiver/StillsPrePass.h | 4 ++++ tools/jfjoch_stills_gpu_replay.cpp | 23 +++++++++++++++++++++-- 5 files changed, 37 insertions(+), 3 deletions(-) diff --git a/receiver/JFJochReceiverRugnuxStills.cpp b/receiver/JFJochReceiverRugnuxStills.cpp index f14ac33ab..3f237f97c 100644 --- a/receiver/JFJochReceiverRugnuxStills.cpp +++ b/receiver/JFJochReceiverRugnuxStills.cpp @@ -161,6 +161,8 @@ void JFJochReceiverRugnuxStills::StillsReady(const StillsSetup &setup) { plots.Setup(setup.experiment, *setup.mapping); DiffractionExperiment written(setup.experiment); written.Goniometer(experiment.GetGoniometer()); + // The cell as stated: the one the frames are indexed on is the analysis's, and the merge reports its own + written.SetUnitCell(experiment.GetUnitCell()); SendStartMessage(MakeStartMessage(written, setup.mask, *setup.mapping)); } diff --git a/receiver/StillsGPUAnalysis.cpp b/receiver/StillsGPUAnalysis.cpp index 7fdc92baa..57f400846 100644 --- a/receiver/StillsGPUAnalysis.cpp +++ b/receiver/StillsGPUAnalysis.cpp @@ -220,6 +220,13 @@ void StillsGPUAnalysis::PrePassThread() { int geometry_frames = 0; if (result) { setup.experiment.BeamX_pxl(result->beam_x_pxl).BeamY_pxl(result->beam_y_pxl).DetectorDistance_mm(result->distance_mm); + // The frames are indexed on the cell refined beside that distance, as offline: the stated cell at the refined + // distance is off in scale by as much as the distance moved (1.7% on a set whose header was that far off) + if (result->cell) + setup.experiment.SetUnitCell(*result->cell); + // and on as many spots as the pre-pass kept, as offline (the broker's default of 250 left a 9M frame of + // ~380 spots a third short of what its lattice is refined on) + setup.experiment.MaxSpotCount(result->max_spot_count); // The frames are integrated as the pre-pass integrated its own: its polarization and background ring setup.experiment.PolarizationFactor(result->polarization); setup.experiment.ImportBraggIntegrationSettings(result->integration); @@ -260,7 +267,7 @@ void StillsGPUAnalysis::PrePassThread() { merge_experiment = setup.experiment; merge_experiment.ImportScalingSettings(RugnuxDefaultScalingSettings(false)); merge = std::make_unique(merge_experiment, experiment.GetImageNum(), - setup.experiment.GetUnitCell(), + experiment.GetUnitCell(), result ? result->run_width : std::nullopt, setup.experiment.IsDetectIceRings(), SpotFindingSettings().ice_ring_width_Q_recipA, logger); diff --git a/receiver/StillsPrePass.cpp b/receiver/StillsPrePass.cpp index eafea8ba1..5f5eb7bf2 100644 --- a/receiver/StillsPrePass.cpp +++ b/receiver/StillsPrePass.cpp @@ -61,6 +61,8 @@ StillsPrePassResult RunStillsPrePass(const StartMessage &start, const std::map cell; + int64_t max_spot_count = 0; // the spots kept per frame, the strongest // What the pre-pass integrated its frames with, for the frames after it: the polarization, the integration // radii and background ring as the pre-scan measured them, and the run's rocking width with the prediction // window made from it (empty where the pre-pass could not measure it). diff --git a/tools/jfjoch_stills_gpu_replay.cpp b/tools/jfjoch_stills_gpu_replay.cpp index ed9747660..c75647cd9 100644 --- a/tools/jfjoch_stills_gpu_replay.cpp +++ b/tools/jfjoch_stills_gpu_replay.cpp @@ -4,7 +4,8 @@ // Replays the frames of a stored serial collection through the broker's live analysis of serial // frames (StillsGPUAnalysis): the pre-pass on the first images, then every frame analysed with the // beam centre and mask it decided. Reports the pre-pass, the indexed fraction and the sustained rate, and -// writes the mask the frames were analysed with (_mask.u32, uint32, row by row). With a model (-m), the +// writes the mask the frames were analysed with (_mask.u32, uint32, row by row), and per frame its spot +// count, indexed spot count and outcome (_images.tsv) and its spots (_spots.tsv). With a model (-m), the // model step of the merges as the broker makes it, and the files the end message would carry: .mtz (the // merge, in the model's frame), _maps.mtz, _model.cif, _refined_model.cif, // _refined_maps.mtz. @@ -59,6 +60,7 @@ void print_usage() { std::cout << " -M no merge (StillsGPUAnalysis merge = false)" << std::endl; std::cout << " -e the first images given as empty frames (no diffraction)" << std::endl; std::cout << " -m model (PDB/mmCIF) placed and refined against the merges" << std::endl; + std::cout << " -p spots kept per image (default: the file's, as the broker's)" << std::endl; std::cout << " -D deadline of the model step after the last image (default 60, 0 = none)" << std::endl; } @@ -73,6 +75,7 @@ int main(int argc, char **argv) { int nthreads = 16; size_t buffer_MiB = 8192; std::optional beam_x, beam_y; + std::optional max_spots; std::optional cell; bool no_cell = false; bool fixed_threshold = false; @@ -83,7 +86,7 @@ int main(int argc, char **argv) { double deadline_s = 60; int opt; - while ((opt = getopt(argc, argv, "o:s:n:r:N:b:x:y:C:cFS:Me:m:D:")) != -1) { + while ((opt = getopt(argc, argv, "o:s:n:r:N:b:x:y:C:cFS:Me:m:D:p:")) != -1) { switch (opt) { case 'o': prefix = optarg; break; case 's': first = atoll(optarg); break; @@ -97,6 +100,7 @@ int main(int argc, char **argv) { case 'F': fixed_threshold = true; break; case 'S': space_group = optarg; break; case 'M': merge = false; break; + case 'p': max_spots = atoll(optarg); break; case 'e': empty_frames = atoll(optarg); break; case 'm': model = std::make_shared(ReadRugnuxModelFile(optarg)); break; case 'D': deadline_s = atof(optarg); break; @@ -139,6 +143,8 @@ int main(int argc, char **argv) { } if (cell) x.SetUnitCell(cell); + if (max_spots) + x.MaxSpotCount(*max_spots); if (space_group) x.SetSpaceGroup(*gemmi::find_spacegroup_by_name(*space_group)); const PixelMask &mask = *dataset->pixel_mask; @@ -175,6 +181,10 @@ int main(int argc, char **argv) { std::unique_ptr run_profile; RugnuxLiveStatus status; // nobody reads it here ReplaySink sink; + std::mutex image_log_mutex; + std::ofstream image_log(prefix + "_images.tsv"), spot_log(prefix + "_spots.tsv"); + image_log << "image\tspots\tindexed_spots\tindexed\n"; + spot_log << "image\tx\ty\tintensity\tindexed\n"; sink.ready = [&](const StillsSetup &setup) { t_ready = std::chrono::steady_clock::now(); run_profile = std::make_unique(*setup.mapping); @@ -186,6 +196,15 @@ int main(int argc, char **argv) { setup.experiment.GetBeamX_pxl(), setup.experiment.GetBeamY_pxl()); }; sink.analysed = [&](DataMessage &m, const AzimuthalIntegrationProfile &profile) { + { + // One line per frame and per spot, to compare frame by frame with an offline run's _process.h5 + std::unique_lock ul(image_log_mutex); + image_log << m.number << '\t' << m.spots.size() << '\t' << m.spot_count_indexed.value_or(0) << '\t' + << m.indexing_result.value_or(false) << '\n'; + for (const auto &s: m.spots) + spot_log << m.number << '\t' << s.x << '\t' << s.y << '\t' << s.intensity << '\t' << s.indexed + << '\n'; + } { // As the receiver's plots do: the frames' profiles add up over the run. std::unique_lock ul(run_profile_mutex); From 4b8ed5c0d591d4e88f178c8fad5d697a5788a822 Mon Sep 17 00:00:00 2001 From: Filip Leonarski Date: Wed, 18 Nov 2026 11:14:25 +0100 Subject: [PATCH 12/41] Revert "CMake: cuFFT linked statically wherever the toolkit has the static library" This reverts commit 3ac1fd657f358ef9221cea25840d980df006e93e. --- CMakeLists.txt | 26 ------------------- image_analysis/geom_refinement/CMakeLists.txt | 2 +- image_analysis/indexing/CMakeLists.txt | 8 +++--- rugnux/CMakeLists.txt | 8 ++++++ tests/CMakeLists.txt | 4 +++ tools/CMakeLists.txt | 4 +++ viewer/CMakeLists.txt | 8 ++++++ 7 files changed, 29 insertions(+), 31 deletions(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index 4626a2392..88e03e81b 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -656,32 +656,6 @@ IF (NOT JFJOCH_WRITER_ONLY AND NOT JFJOCH_PORTABLE_ONLY) INSTALL(DIRECTORY ${CMAKE_SOURCE_DIR}/frontend/dist/ DESTINATION share/jfjoch/frontend COMPONENT jfjoch ) ENDIF() -# libcufft_static.a carries a relocatable-device-code object (separate_callback.o), so an executable -# linking it needs a CUDA device-link step -- without it the host link fails on an undefined -# __cudaRegisterLinkedBinary_* symbol. CUDA 13 no longer ships libcufft_static_nocallback.a, which -# used to be the way around it. CUDA_RESOLVE_DEVICE_SYMBOLS makes CMake emit that step while leaving -# the host link driver alone, so the -march/-flto flags CI passes still apply. Set on every executable -# and shared library of this source tree, as nearly all of them link the image analysis. -FUNCTION(JFJOCH_RESOLVE_DEVICE_SYMBOLS dir) - GET_PROPERTY(_targets DIRECTORY ${dir} PROPERTY BUILDSYSTEM_TARGETS) - FOREACH(_target IN LISTS _targets) - GET_TARGET_PROPERTY(_type ${_target} TYPE) - IF (_type MATCHES "EXECUTABLE|SHARED_LIBRARY|MODULE_LIBRARY") - SET_TARGET_PROPERTIES(${_target} PROPERTIES CUDA_RESOLVE_DEVICE_SYMBOLS ON) - ENDIF() - ENDFOREACH() - GET_PROPERTY(_subdirs DIRECTORY ${dir} PROPERTY SUBDIRECTORIES) - FOREACH(_subdir IN LISTS _subdirs) - STRING(FIND "${_subdir}" "${CMAKE_SOURCE_DIR}/" _position) - IF (_position EQUAL 0) # not the fetched dependencies - JFJOCH_RESOLVE_DEVICE_SYMBOLS(${_subdir}) - ENDIF() - ENDFOREACH() -ENDFUNCTION() -IF (JFJOCH_CUDA_AVAILABLE AND TARGET CUDA::cufft_static) - JFJOCH_RESOLVE_DEVICE_SYMBOLS(${CMAKE_SOURCE_DIR}) -ENDIF() - # Windows has no static cuFFT (the toolkit ships no cufft_static.lib), so there the indexer links # the import library and the self-contained products must carry the DLL beside the executable -- # the same idea the Linux builds no longer need, since they link libcufft_static.a. CUDA 13 keeps diff --git a/image_analysis/geom_refinement/CMakeLists.txt b/image_analysis/geom_refinement/CMakeLists.txt index 74659539b..a82fee507 100644 --- a/image_analysis/geom_refinement/CMakeLists.txt +++ b/image_analysis/geom_refinement/CMakeLists.txt @@ -47,7 +47,7 @@ IF (JFJOCH_CUDA_AVAILABLE) BeamCenterBackgroundGPU.cu BeamCenterBackgroundGPU.h) # Same static/dynamic cuFFT choice as the FFT indexer, and for the same reasons - see the long # note in image_analysis/indexing/CMakeLists.txt. - IF (TARGET CUDA::cufft_static) + IF (JFJOCH_PORTABLE_ONLY AND TARGET CUDA::cufft_static) TARGET_LINK_LIBRARIES(JFJochGeomRefinement CUDA::cufft_static) ELSE() TARGET_LINK_LIBRARIES(JFJochGeomRefinement CUDA::cufft) diff --git a/image_analysis/indexing/CMakeLists.txt b/image_analysis/indexing/CMakeLists.txt index 66f005b10..e7d787197 100644 --- a/image_analysis/indexing/CMakeLists.txt +++ b/image_analysis/indexing/CMakeLists.txt @@ -51,10 +51,10 @@ IF (JFJOCH_CUDA_AVAILABLE) # and the dynamic library is the only option; the top-level CMakeLists installs the DLL beside # the executable for the self-contained builds. Test the target rather than the platform, so a # toolkit that gains or loses the static library is handled without another special case. - # The server build links it statically too, so its executables (broker, tools copied to another - # machine) need no CUDA toolkit library; the top-level CMakeLists gives every executable the device - # link this needs. - IF (TARGET CUDA::cufft_static) + # Both halves matter: the server build keeps the shared library (its .deb/.rpm take CUDA from the + # distro, and every executable there -- broker, tests, tools -- would otherwise need the device + # link below), and Windows has no static cuFFT to link even for the portable products. + IF (JFJOCH_PORTABLE_ONLY AND TARGET CUDA::cufft_static) TARGET_LINK_LIBRARIES(JFJochIndexing fast_indexer_static CUDA::cufft_static) ELSE() TARGET_LINK_LIBRARIES(JFJochIndexing fast_indexer_static CUDA::cufft) diff --git a/rugnux/CMakeLists.txt b/rugnux/CMakeLists.txt index 132d93764..12db3d061 100644 --- a/rugnux/CMakeLists.txt +++ b/rugnux/CMakeLists.txt @@ -66,6 +66,14 @@ IF(APPLE AND JFJOCH_MACOS_SIGNING_IDENTITY) COMPONENT rugnux) ENDIF() +# libcufft_static.a carries a relocatable-device-code object (separate_callback.o), so an executable +# linking it needs a CUDA device-link step -- without it the host link fails on an undefined +# __cudaRegisterLinkedBinary_* symbol. CUDA 13 no longer ships libcufft_static_nocallback.a, which +# used to be the way around it. CUDA_RESOLVE_DEVICE_SYMBOLS makes CMake emit that step while leaving +# the host link driver alone, so the -march/-flto flags CI passes still apply. +IF (JFJOCH_PORTABLE_ONLY AND JFJOCH_CUDA_AVAILABLE AND TARGET CUDA::cufft_static) + SET_TARGET_PROPERTIES(rugnux PROPERTIES CUDA_RESOLVE_DEVICE_SYMBOLS ON) +ENDIF() # On Windows this CLI gets getopt/getopt_long from the vendored wingetopt shim (libc has none). diff --git a/tests/CMakeLists.txt b/tests/CMakeLists.txt index ed7af1f68..f30cb28c6 100644 --- a/tests/CMakeLists.txt +++ b/tests/CMakeLists.txt @@ -47,6 +47,10 @@ ADD_EXECUTABLE(jfjoch_portable_test EXCLUDE_FROM_ALL target_link_libraries(jfjoch_portable_test Catch2WithMain JFJochRugnux JFJochReader JFJochImageAnalysis JFJochWriter JFJochAPIConvert JFJochCommon) target_include_directories(jfjoch_portable_test PRIVATE .) +# Same device-link step as rugnux (see rugnux/CMakeLists.txt): a portable CUDA build links cuFFT statically. +IF (JFJOCH_PORTABLE_ONLY AND JFJOCH_CUDA_AVAILABLE AND TARGET CUDA::cufft_static) + SET_TARGET_PROPERTIES(jfjoch_portable_test PROPERTIES CUDA_RESOLVE_DEVICE_SYMBOLS ON) +ENDIF() # The CPU vs GPU test of the fast-feedback indexer reads the library's own test spot lists IF (JFJOCH_CUDA_AVAILABLE) diff --git a/tools/CMakeLists.txt b/tools/CMakeLists.txt index 74d302a1c..9fdf2e2a9 100644 --- a/tools/CMakeLists.txt +++ b/tools/CMakeLists.txt @@ -18,6 +18,10 @@ TARGET_LINK_LIBRARIES(jfjoch_extract_hkl JFJochReader) # measuring the refinement on battery outputs without processing anything again. ADD_EXECUTABLE(rugnux_refine_test rugnux_refine_test.cpp) TARGET_LINK_LIBRARIES(rugnux_refine_test JFJochStructureRefinement JFJochCommon gemmi) +# Same device-link step as rugnux (see rugnux/CMakeLists.txt): a portable CUDA build links cuFFT statically. +IF (JFJOCH_PORTABLE_ONLY AND JFJOCH_CUDA_AVAILABLE AND TARGET CUDA::cufft_static) + SET_TARGET_PROPERTIES(rugnux_refine_test PROPERTIES CUDA_RESOLVE_DEVICE_SYMBOLS ON) +ENDIF() # In-place re-compress /entry/data/data of a _data file from bitshuffle/LZ4 to bitshuffle/zstd. ADD_EXECUTABLE(jfjoch_recompress jfjoch_recompress.cpp) diff --git a/viewer/CMakeLists.txt b/viewer/CMakeLists.txt index ec62a3b68..0345b7587 100644 --- a/viewer/CMakeLists.txt +++ b/viewer/CMakeLists.txt @@ -184,6 +184,14 @@ IF(APPLE) PATTERN "COLLECT.sh" EXCLUDE) ENDIF() +# libcufft_static.a carries a relocatable-device-code object (separate_callback.o), so an executable +# linking it needs a CUDA device-link step -- without it the host link fails on an undefined +# __cudaRegisterLinkedBinary_* symbol. CUDA 13 no longer ships libcufft_static_nocallback.a, which +# used to be the way around it. CUDA_RESOLVE_DEVICE_SYMBOLS makes CMake emit that step while leaving +# the host link driver alone, so the -march/-flto flags CI passes still apply. +IF (JFJOCH_PORTABLE_ONLY AND JFJOCH_CUDA_AVAILABLE AND TARGET CUDA::cufft_static) + SET_TARGET_PROPERTIES(jfjoch_viewer PROPERTIES CUDA_RESOLVE_DEVICE_SYMBOLS ON) +ENDIF() IF(JFJOCH_VIEWER_DBUS) From 41f7edab76a5f8e0d36ed5de1a225cd84d8f395f Mon Sep 17 00:00:00 2001 From: Filip Leonarski Date: Wed, 18 Nov 2026 11:15:49 +0100 Subject: [PATCH 13/41] CMake: cuFFT static for jfjoch_fpga_stills_test alone The other builds link cuFFT as before (dynamic on the server build, static in the portable ones). jfjoch_fpga_stills_test is copied to the FPGA servers on its own: its JFJOCH_STATIC_CUFFT property makes the indexer and the beam-centre FFT, which choose by a generator expression on the linking target, give it libcufft_static.a, and it gets the device-link step that needs. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01UqXYdHHZ4cogS1mrGUtfN7 --- image_analysis/geom_refinement/CMakeLists.txt | 3 +++ image_analysis/indexing/CMakeLists.txt | 5 +++++ tools/CMakeLists.txt | 5 +++++ 3 files changed, 13 insertions(+) diff --git a/image_analysis/geom_refinement/CMakeLists.txt b/image_analysis/geom_refinement/CMakeLists.txt index a82fee507..e17df4797 100644 --- a/image_analysis/geom_refinement/CMakeLists.txt +++ b/image_analysis/geom_refinement/CMakeLists.txt @@ -49,6 +49,9 @@ IF (JFJOCH_CUDA_AVAILABLE) # note in image_analysis/indexing/CMakeLists.txt. IF (JFJOCH_PORTABLE_ONLY AND TARGET CUDA::cufft_static) TARGET_LINK_LIBRARIES(JFJochGeomRefinement CUDA::cufft_static) + ELSEIF (TARGET CUDA::cufft_static) + TARGET_LINK_LIBRARIES(JFJochGeomRefinement + $>,CUDA::cufft_static,CUDA::cufft>) ELSE() TARGET_LINK_LIBRARIES(JFJochGeomRefinement CUDA::cufft) ENDIF() diff --git a/image_analysis/indexing/CMakeLists.txt b/image_analysis/indexing/CMakeLists.txt index e7d787197..e2e33ebaa 100644 --- a/image_analysis/indexing/CMakeLists.txt +++ b/image_analysis/indexing/CMakeLists.txt @@ -54,8 +54,13 @@ IF (JFJOCH_CUDA_AVAILABLE) # Both halves matter: the server build keeps the shared library (its .deb/.rpm take CUDA from the # distro, and every executable there -- broker, tests, tools -- would otherwise need the device # link below), and Windows has no static cuFFT to link even for the portable products. + # One exception in the server build: an executable with the JFJOCH_STATIC_CUFFT property (set on + # jfjoch_fpga_stills_test, which is copied to the FPGA servers on its own) gets the static library. IF (JFJOCH_PORTABLE_ONLY AND TARGET CUDA::cufft_static) TARGET_LINK_LIBRARIES(JFJochIndexing fast_indexer_static CUDA::cufft_static) + ELSEIF (TARGET CUDA::cufft_static) + TARGET_LINK_LIBRARIES(JFJochIndexing fast_indexer_static + $>,CUDA::cufft_static,CUDA::cufft>) ELSE() TARGET_LINK_LIBRARIES(JFJochIndexing fast_indexer_static CUDA::cufft) ENDIF() diff --git a/tools/CMakeLists.txt b/tools/CMakeLists.txt index 9fdf2e2a9..18379427a 100644 --- a/tools/CMakeLists.txt +++ b/tools/CMakeLists.txt @@ -70,6 +70,11 @@ IF(NOT JFJOCH_PORTABLE_ONLY) ADD_EXECUTABLE(jfjoch_fpga_stills_test jfjoch_fpga_stills_test.cpp) TARGET_LINK_LIBRARIES(jfjoch_fpga_stills_test JFJochReceiver JFJochReader) + # Copied to the FPGA servers on its own: cuFFT linked statically (see image_analysis/indexing/CMakeLists.txt), + # which needs the device-link step (see rugnux/CMakeLists.txt) + IF (JFJOCH_CUDA_AVAILABLE AND TARGET CUDA::cufft_static) + SET_TARGET_PROPERTIES(jfjoch_fpga_stills_test PROPERTIES JFJOCH_STATIC_CUFFT ON CUDA_RESOLVE_DEVICE_SYMBOLS ON) + ENDIF() INSTALL(TARGETS jfjoch_fpga_stills_test RUNTIME COMPONENT jfjoch) ADD_EXECUTABLE(jfjoch_simplon_test jfjoch_simplon_test.cpp) From 702b8d4a68c23f7acadf519b94ba27e9308d3193 Mon Sep 17 00:00:00 2001 From: Filip Leonarski Date: Wed, 18 Nov 2026 11:49:09 +0100 Subject: [PATCH 14/41] Live stills: a frame with no free slot during the pre-pass waits as its compressed bytes Every frame that arrives before the pre-pass is over waits for the analysis, and each took a slot of the image buffer, sized for an uncompressed frame plus metadata (24 MB on a 9M detector for a frame of ~1.5 MB compressed). Not blocking, the frames past the buffer were dropped: on the mock, 9M, 2 cards, 1500 frames at ~140 Hz, a 13-17 s pre-pass, 683 of 1186-1400 collected were sent. A frame that finds no slot is now held as a copy of its compressed bytes, up to the image buffer's size again; a slot still comes first (the frame can be seen there while it waits), and the frame is sent from a fresh slot after its analysis as before. Same mock run: 1462-1489 of 1462-1489 collected sent (the rest are the mock puller's own module drops), peak RSS 27.1 -> 27.7 GB. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01UqXYdHHZ4cogS1mrGUtfN7 --- receiver/JFJochReceiverRugnuxStills.cpp | 73 +++++++++++++++---------- receiver/JFJochReceiverRugnuxStills.h | 5 ++ receiver/StillsPrePass.h | 8 ++- tests/JFJochReceiverRugnuxTest.cpp | 5 +- 4 files changed, 60 insertions(+), 31 deletions(-) diff --git a/receiver/JFJochReceiverRugnuxStills.cpp b/receiver/JFJochReceiverRugnuxStills.cpp index 3f237f97c..b80066f07 100644 --- a/receiver/JFJochReceiverRugnuxStills.cpp +++ b/receiver/JFJochReceiverRugnuxStills.cpp @@ -48,6 +48,7 @@ JFJochReceiverRugnuxStills::~JFJochReceiverRugnuxStills() { void JFJochReceiverRugnuxStills::OnStart(std::chrono::steady_clock::time_point received) { const int64_t slots = image_buffer.GetStatus().total_slots; stills_keep_free = std::min(stills_nthreads, slots / 2); + copy_budget = slots * experiment.GetImageBufferLocationSize(); const StartMessage start = MakeStartMessage(experiment, pixel_mask, *az_int_mapping); // The frames are shown from their arrival, on the stated geometry until the pre-pass has decided its own. // To the image buffer only: the writer and the ZeroMQ streams get the one start message, after the pre-pass. @@ -82,43 +83,59 @@ void JFJochReceiverRugnuxStills::OnImage(uint32_t id, DataMessage &message, std: CountImage(message); const size_t size = message.image.GetCompressedSize(); - // Waits for the analysis in a slot of the image buffer; a slot is kept free for each analysis thread to send with + // Waits for the analysis in a slot of the image buffer, where it can be seen while it waits (it is not sent from + // there); a slot is kept free for each analysis thread to send with. Without a slot, in a copy of its own. auto held = std::make_shared(); - held->slot = image_buffer.GetImageSlot(stills_keep_free); - while ((held->slot == nullptr) && image_puller.IsBlocking() && !cancelled) { - std::this_thread::sleep_for(std::chrono::milliseconds(1)); + const auto hold = [&] { held->slot = image_buffer.GetImageSlot(stills_keep_free); + if (held->slot == nullptr) { + if (copy_bytes.fetch_add(static_cast(size)) + static_cast(size) <= copy_budget) { + held->copy.assign(message.image.GetCompressed(), message.image.GetCompressed() + size); + held->copy_bytes = ©_bytes; + } else + copy_bytes -= static_cast(size); + } + return held->slot != nullptr || held->copy_bytes != nullptr; + }; + bool held_ok = hold(); + while (!held_ok && image_puller.IsBlocking() && !cancelled) { + std::this_thread::sleep_for(std::chrono::milliseconds(1)); + held_ok = hold(); } - if (held->slot == nullptr) { + if (!held_ok) { writer_queue_full = true; return; } held->message = message; StampImage(held->message, image_puller.GetCurrentFifoUtilization()); - // In the slot as an image without analysis, so that it can be seen while it waits; it is not sent. The - // analysis reads the image where it is in the slot. - auto slot_buffer = static_cast(held->slot->GetImage()); - CBORStream2Serializer serializer(slot_buffer, experiment.GetImageBufferLocationSize()); - held->message.image = CompressedImage(nullptr, 0, message.image.GetWidth(), message.image.GetHeight(), - message.image.GetMode(), message.image.GetCompressionAlgorithm(), - message.image.GetChannel()); - serializer.SerializeImage(held->message); - const size_t image_offset = serializer.GetImageAppendOffset(); - if (image_offset + size + 32 >= static_cast(experiment.GetImageBufferLocationSize())) { - logger.Error("Dropping image {} - metadata {} B + image {} B do not fit in buffer slot {} B", message.number, - image_offset, size, experiment.GetImageBufferLocationSize()); - return; - } - memcpy(slot_buffer + image_offset, message.image.GetCompressed(), size); - serializer.AppendImage(size); - held->message.image = CompressedImage(slot_buffer + image_offset, size, message.image.GetWidth(), - message.image.GetHeight(), message.image.GetMode(), - message.image.GetCompressionAlgorithm(), message.image.GetChannel()); - held->slot->SetImageNumber(message.number); - held->slot->SetImageSize(serializer.GetBufferSize()); - held->slot->SetIndexed(false); - held->slot->ReadyToSend(); + if (held->slot) { + // In the slot as an image without analysis; the analysis reads the image where it is in the slot. + auto slot_buffer = static_cast(held->slot->GetImage()); + CBORStream2Serializer serializer(slot_buffer, experiment.GetImageBufferLocationSize()); + held->message.image = CompressedImage(nullptr, 0, message.image.GetWidth(), message.image.GetHeight(), + message.image.GetMode(), message.image.GetCompressionAlgorithm(), + message.image.GetChannel()); + serializer.SerializeImage(held->message); + const size_t image_offset = serializer.GetImageAppendOffset(); + if (image_offset + size + 32 >= static_cast(experiment.GetImageBufferLocationSize())) { + logger.Error("Dropping image {} - metadata {} B + image {} B do not fit in buffer slot {} B", message.number, + image_offset, size, experiment.GetImageBufferLocationSize()); + return; + } + memcpy(slot_buffer + image_offset, message.image.GetCompressed(), size); + serializer.AppendImage(size); + held->message.image = CompressedImage(slot_buffer + image_offset, size, message.image.GetWidth(), + message.image.GetHeight(), message.image.GetMode(), + message.image.GetCompressionAlgorithm(), message.image.GetChannel()); + held->slot->SetImageNumber(message.number); + held->slot->SetImageSize(serializer.GetBufferSize()); + held->slot->SetIndexed(false); + held->slot->ReadyToSend(); + } else + held->message.image = CompressedImage(held->copy.data(), size, message.image.GetWidth(), + message.image.GetHeight(), message.image.GetMode(), + message.image.GetCompressionAlgorithm(), message.image.GetChannel()); stills->Hold(held); } diff --git a/receiver/JFJochReceiverRugnuxStills.h b/receiver/JFJochReceiverRugnuxStills.h index 1a4ab1b94..3f4d8ba4e 100644 --- a/receiver/JFJochReceiverRugnuxStills.h +++ b/receiver/JFJochReceiverRugnuxStills.h @@ -21,6 +21,11 @@ class JFJochReceiverRugnuxStills : public JFJochReceiverStream, public StillsSin IndexerThreadPool *const indexing_thread_pool; const int64_t stills_nthreads; int64_t stills_keep_free = 0; // slots frames do not take, for the analysis threads to send with + // Frames that find no free slot while they wait for the analysis are held as their compressed bytes, up to the + // image buffer's size again: the pre-pass holds every frame that arrives before it is over, and a frame is a + // fraction of a slot (1.5 MB of a 24 MB slot on a 9M detector) + int64_t copy_budget = 0; + std::atomic copy_bytes = 0; std::mutex stills_mutex; bool cut = false; diff --git a/receiver/StillsPrePass.h b/receiver/StillsPrePass.h index 33b564eb7..2a3765664 100644 --- a/receiver/StillsPrePass.h +++ b/receiver/StillsPrePass.h @@ -3,6 +3,7 @@ #pragma once +#include #include #include #include @@ -15,10 +16,13 @@ #include "../image_analysis/IndexAndRefine.h" // StillsWindow // An image held until analysed, pointing into `slot`, which goes back unsent with the last copy. The slot is -// forgotten then, so that the copy sent with the analysis is the only one the image buffer finds. +// forgotten then, so that the copy sent with the analysis is the only one the image buffer finds. Where no slot +// was free, the image points into `copy` instead, its compressed bytes, counted in `copy_bytes` while held. struct HeldImage { DataMessage message; ZeroCopyReturnValue *slot = nullptr; + std::vector copy; + std::atomic *copy_bytes = nullptr; HeldImage() = default; HeldImage(const HeldImage &) = delete; @@ -26,6 +30,8 @@ struct HeldImage { ~HeldImage() { if (slot) slot->discard(); + if (copy_bytes) + *copy_bytes -= static_cast(copy.size()); } }; diff --git a/tests/JFJochReceiverRugnuxTest.cpp b/tests/JFJochReceiverRugnuxTest.cpp index 18789f6c5..167167439 100644 --- a/tests/JFJochReceiverRugnuxTest.cpp +++ b/tests/JFJochReceiverRugnuxTest.cpp @@ -663,10 +663,11 @@ TEST_CASE("JFJochReceiverRugnux_Stills_BufferFullDuringPrePass", "[JFJochReceive CHECK(!out.status.cancelled); CHECK(pusher.Events() == std::vector{"start", "image", "end"}); - // A frame that finds no free slot is not written, and the collection says so. + // A frame that finds no free slot waits in a copy of its own, and is written. CHECK(out.status.images_collected == images); CHECK(out.efficiency == 1.0f); - CHECK(out.writer_queue_full_warning == (out.status.images_sent < images)); + CHECK(out.status.images_sent == images); + CHECK(!out.writer_queue_full_warning); CHECK(out.scan_result.images.size() == out.status.images_sent); REQUIRE(pusher.End()); CHECK(pusher.End()->images_collected_count == images); From f2e4dc63b4bc847edf99f323f73018493c321d39 Mon Sep 17 00:00:00 2001 From: Filip Leonarski Date: Wed, 18 Nov 2026 12:19:07 +0100 Subject: [PATCH 15/41] Receivers: rugnux live only through FPGAImagePuller, pedestal runs on JFJochReceiverPedestal - JFJochReceiverFPGA no longer runs rugnux: its live stills (StillsGPUAnalysisFPGA, GPUSink, the merged data in END) and its pedestal code go; the receiver is the one of rc186 (rc186-old), which differs from what it replaces only in these two parts. - JFJochReceiverPedestal back from rc186 (242587c58, 7080109a4) unchanged: raw frames from the devices into JFPedestalCalc, nothing on any socket. In rc186 it took every PSI pedestal run directly from the devices, not through the puller; so it does here. - Dispatch for a PSI detector: pedestal -> JFJochReceiverPedestal; rugnux live on (Standard mode, no host summation) -> FPGAImagePuller and JFJochReceiverRugnuxStills or ...Rotation; otherwise JFJochReceiverFPGA, unchanged. With host summation rugnux live is not run (a warning in the status). - The FPGAImagePullerUse enum goes: FPGAImagePullerSettings(slots, blocking, rate, always), where always (every collection through the puller, without rugnux to JFJochReceiverLite) is kept for the tests comparing the puller with JFJochReceiverFPGA pixel for pixel. - jfjoch_fpga_stills_test loses -F; StillsGPUAnalysisFPGATest goes, the GPU-stills processing tests run the puller path only. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01UqXYdHHZ4cogS1mrGUtfN7 --- docs/TOOLS.md | 7 +- receiver/CMakeLists.txt | 2 +- receiver/JFJochReceiverFPGA.cpp | 362 ++------------------- receiver/JFJochReceiverFPGA.h | 31 +- receiver/JFJochReceiverPedestal.cpp | 242 ++++++++++++++ receiver/JFJochReceiverPedestal.h | 63 ++++ receiver/JFJochReceiverService.cpp | 34 +- receiver/JFJochReceiverService.h | 15 +- receiver/StillsGPUAnalysisFPGA.cpp | 419 ------------------------- receiver/StillsGPUAnalysisFPGA.h | 151 --------- tests/CMakeLists.txt | 1 - tests/FPGAImagePullerTest.cpp | 12 +- tests/JFJochReceiverProcessingTest.cpp | 6 - tests/StillsGPUAnalysisFPGATest.cpp | 127 -------- tools/jfjoch_fpga_stills_test.cpp | 21 +- 15 files changed, 381 insertions(+), 1112 deletions(-) create mode 100644 receiver/JFJochReceiverPedestal.cpp create mode 100644 receiver/JFJochReceiverPedestal.h delete mode 100644 receiver/StillsGPUAnalysisFPGA.cpp delete mode 100644 receiver/StillsGPUAnalysisFPGA.h delete mode 100644 tests/StillsGPUAnalysisFPGATest.cpp diff --git a/docs/TOOLS.md b/docs/TOOLS.md index 56cfe734f..30da17140 100644 --- a/docs/TOOLS.md +++ b/docs/TOOLS.md @@ -74,7 +74,7 @@ synthesis C model on the CPU, so no FPGA device is required. Measures rugnux live stills on the FPGA card(s), with a stored dataset standing in for the detector: ``` -jfjoch_fpga_stills_test [-i ] [-s ] [-N ] [-B ] [-C a,b,c,al,be,ga] [-X ] [-r ,...] [-p ] [-F] [-K[]] +jfjoch_fpga_stills_test [-i ] [-s ] [-N ] [-B ] [-C a,b,c,al,be,ga] [-X ] [-r ,...] [-p ] [-d] [-v] [-K[]] ``` - The dataset must be a stored JUNGFRAU dataset with its modules assembled (1030 x 514 each, any placement @@ -87,9 +87,8 @@ jfjoch_fpga_stills_test [-i ] [-s ] [-N ] [-B ] [-C one is saturated or the sum exceeds 16 bits it is saturated. - The frames are loaded into the card's internal frame generator and the run is made with the JUNGFRAU conversion off, so the card returns them verbatim; the host assembles them as signed 16-bit photon - counts and rugnux live stills analyses them through `FPGAImagePuller` (`-F`: through - `JFJochReceiverFPGA`'s own live stills, for comparison; that path does not block: frames past what its - analysis holds are lost and counted). Beam centre, distance, energy and the cell + counts and rugnux live stills analyses them through `FPGAImagePuller`, as the broker does with rugnux live + on (`-d`: not blocking, as the broker runs; `-v`: each card's progress every 0.5 s). Beam centre, distance, energy and the cell come from the file (`-C` overrides the cell; without one the frames are indexed de novo). Nothing is written. - Each card's generator holds module frames of its own modules only: as many images as its memory holds diff --git a/receiver/CMakeLists.txt b/receiver/CMakeLists.txt index c49af596f..5cc13a491 100644 --- a/receiver/CMakeLists.txt +++ b/receiver/CMakeLists.txt @@ -7,6 +7,7 @@ ADD_LIBRARY(JFJochReceiver STATIC JFJochReceiverService.cpp JFJochReceiverService.h JFJochReceiverTest.cpp JFJochReceiverTest.h JFJochReceiverFPGA.cpp JFJochReceiverFPGA.h + JFJochReceiverPedestal.cpp JFJochReceiverPedestal.h ImageMetadata.cpp ImageMetadata.h LossyFilter.cpp @@ -21,7 +22,6 @@ ADD_LIBRARY(JFJochReceiver STATIC JFJochReceiverRugnuxStills.h JFJochReceiverRugnuxStills.cpp StillsPrePass.h StillsPrePass.cpp StillsGPUAnalysis.h StillsGPUAnalysis.cpp - StillsGPUAnalysisFPGA.h StillsGPUAnalysisFPGA.cpp RugnuxLiveStatus.h RugnuxLiveStatus.cpp RugnuxStructure.h RugnuxStructure.cpp JFJochReceiver.cpp diff --git a/receiver/JFJochReceiverFPGA.cpp b/receiver/JFJochReceiverFPGA.cpp index 163eaa553..09bc6d2a1 100644 --- a/receiver/JFJochReceiverFPGA.cpp +++ b/receiver/JFJochReceiverFPGA.cpp @@ -3,14 +3,9 @@ #include "JFJochReceiverFPGA.h" -#include "../image_analysis/WriteReflections.h" - #include #include "ImageMetadata.h" -#include "JFJochReceiverLite.h" -#include "../common/CUDAWrapper.h" -#include "../image_analysis/MXAnalysisWithoutFPGA.h" JFJochReceiverFPGA::JFJochReceiverFPGA(const DiffractionExperiment &in_experiment, const PixelMask &in_pixel_mask, @@ -24,9 +19,7 @@ JFJochReceiverFPGA::JFJochReceiverFPGA(const DiffractionExperiment &in_experimen ImageBuffer &in_send_buf_ctrl, ZMQPreviewSocket *in_zmq_preview_socket, ZMQMetadataSocket *in_zmq_metadata_socket, - IndexerThreadPool *indexing_thread_pool, - bool in_gpu_analysis, - RugnuxLiveStatus *in_rugnux_status) + IndexerThreadPool *indexing_thread_pool) : JFJochReceiver(in_experiment, in_send_buf_ctrl, in_image_sender, @@ -44,13 +37,9 @@ JFJochReceiverFPGA::JFJochReceiverFPGA(const DiffractionExperiment &in_experimen ndatastreams(experiment.GetDataStreamsNum()), frame_transformation_nthreads( in_forward_and_sum_nthreads), - pedestal_nthreads((experiment.GetStorageCellNumber() > 2) ? 1 : 4), summation_nthreads(2), - frame_transformation_ready((experiment.GetImageNum() > 0) ? frame_transformation_nthreads : 0), - data_acquisition_ready(ndatastreams), - gpu_analysis(in_gpu_analysis && experiment.GetImageNum() > 0 - && experiment.GetDetectorMode() == DetectorMode::Standard), - rugnux_status(in_rugnux_status) { + frame_transformation_ready(frame_transformation_nthreads), + data_acquisition_ready(ndatastreams) { // The FPGA integration core has a fixed bin-count limit. Reject configurations it cannot // handle before starting acquisition, unless azimuthal integration is forced onto the CPU. const auto &azint_settings = experiment.GetAzimuthalIntegrationSettings(); @@ -92,92 +81,23 @@ JFJochReceiverFPGA::JFJochReceiverFPGA(const DiffractionExperiment &in_experimen logger.Debug("Data acquisition devices ready"); - if ((experiment.GetDetectorMode() == DetectorMode::PedestalG0) - || (experiment.GetDetectorMode() == DetectorMode::PedestalG1) - || (experiment.GetDetectorMode() == DetectorMode::PedestalG2)) { - if (experiment.GetImageNum() > 0) { - throw JFJochException(JFJochExceptionCategory::InputParameterInvalid, - "Saving and calculating pedestal is not supported for the time being"); - } + SendStartMessage(); + SendCalibration(); - switch (experiment.GetDetectorMode()) { - case DetectorMode::PedestalG1: - only_2nd_sc_pedestal = !experiment.IsFixedGainG1() && (experiment.GetStorageCellNumber() == 2); - break; - case DetectorMode::PedestalG2: - only_2nd_sc_pedestal = (experiment.GetStorageCellNumber() == 2); - break; - default: - only_2nd_sc_pedestal = false; - break; - } + for (int i = 0; i < experiment.GetImageNum(); i++) + images_to_go.Put(i); - int64_t pedestal_count = (only_2nd_sc_pedestal) - ? experiment.GetModulesNum() - : experiment.GetModulesNum() * experiment.GetStorageCellNumber(); - for (int i = 0; i < pedestal_count; i++) - pedestal.emplace_back(std::make_unique(experiment)); - - for (int s = 0; s < experiment.GetStorageCellNumber(); s++) { - bool ignore = only_2nd_sc_pedestal && (s == 0); - for (int d = 0; d < ndatastreams; d++) - for (int m = 0; m < experiment.GetModulesNum(d); m++) - for (int n = 0; n < pedestal_nthreads; n++) - frame_transformation_futures.emplace_back(std::async(std::launch::async, - &JFJochReceiverFPGA::MeasurePedestalThread, - this, d, m, s, n, ignore)); - } - logger.Debug("Pedestal threads ready ({} threads/module*SC)", pedestal_nthreads); - } else if (experiment.GetImageNum() > 0) { - if (gpu_analysis) { - // The start message and the calibration go out once the pre-pass is done. - gpu = std::make_unique( - experiment, pixel_mask, MakeStartMessage(experiment, pixel_mask, *az_int_mapping), - indexing_thread_pool, std::min(16, frame_transformation_nthreads), - // Half the image buffer for the frames waiting, the other half for those sent. - image_buffer.GetStatus().total_slots / 2, logger, - [this](const StillsGPUAnalysisFPGA::Setup &s) { - // The profiles are binned on the pre-pass's geometry. - plots.Setup(s.experiment, *s.mapping); - SendStartMessage(MakeStartMessage(s.experiment, s.mask, *s.mapping)); - SendCalibration(); - }, - [this](DataMessage &m, const AzimuthalIntegrationProfile &p) { GPUSink(m, p); }, - [this] { - // The broker's settings, with the spot finder rugnux uses on stills (the pre-pass - // decided the centre and mask with it): adaptive threshold, single-pixel spots kept. - // With the broker's default fixed threshold 3 points fewer frames index. - // Every frame is integrated: integration is rugnux's, not the broker's to switch off. - SpotFindingSettings s = GetSpotFindingSettings(); - s.adaptive_threshold = true; - s.min_pix_per_spot = std::nullopt; - s.quick_integration = true; - return s; - }, - // The start message did not go out (or the analysis could not be set up): nothing can - // be written, so the collection stops, as it does on an error in a frame thread. - [this](const JFJochException &e) { Cancel(e); }, - rugnux_status); - } else { - SendStartMessage(); - SendCalibration(); - } - - for (int i = 0; i < experiment.GetImageNum(); i++) - images_to_go.Put(i); - - // Setup frames summation and forwarding - for (uint32_t i = 0; i < frame_transformation_nthreads; i++) { - auto handle = std::async(std::launch::async, &JFJochReceiverFPGA::FrameTransformationThread, - this, i); - frame_transformation_futures.emplace_back(std::move(handle)); - } - - logger.Debug("Image compression/forwarding threads started ({} threads)", frame_transformation_nthreads); - frame_transformation_ready.wait(); - logger.Debug("Image compression/forwarding threads ready"); + // Setup frames summation and forwarding + for (uint32_t i = 0; i < frame_transformation_nthreads; i++) { + auto handle = std::async(std::launch::async, &JFJochReceiverFPGA::FrameTransformationThread, + this, i); + frame_transformation_futures.emplace_back(std::move(handle)); } + logger.Debug("Image compression/forwarding threads started ({} threads)", frame_transformation_nthreads); + frame_transformation_ready.wait(); + logger.Debug("Image compression/forwarding threads ready"); + for (int d = 0; d < ndatastreams; d++) data_acquisition_futures.emplace_back(std::async(std::launch::async, &JFJochReceiverFPGA::AcquireThread, this, d)); @@ -251,49 +171,11 @@ void JFJochReceiverFPGA::AcquireThread(uint16_t data_stream) { } -void JFJochReceiverFPGA::MeasurePedestalThread(uint16_t data_stream, uint16_t module_number, uint16_t storage_cell, - uint32_t threadid, bool ignore) { - JFPedestalCalc pedestal_calc(experiment); - - uint64_t starting_frame = storage_cell + threadid * experiment.GetStorageCellNumber(); - uint64_t frame_stride = experiment.GetStorageCellNumber() * pedestal_nthreads; - uint32_t storage_cell_header = UINT32_MAX; - - try { - for (size_t frame = starting_frame; frame < experiment.GetFrameNum(); frame += frame_stride) { - // Frame will be processed only if one already collects frame+2 - acquisition_device[data_stream].Counters().WaitForFrame(frame + 2, module_number); - if (acquisition_device[data_stream].Counters().IsFullModuleCollected(frame, module_number) && !ignore) { - auto output = acquisition_device[data_stream].GetDeviceOutput(frame, module_number); - // Partial packets will bring more problems, than benefit - pedestal_calc.AnalyzeImage((uint16_t *) output->pixels); - storage_cell_header = (output->module_statistics.debug >> 8) & 0xF; - } - acquisition_device[data_stream].FrameBufferRelease(frame, module_number); - - UpdateMaxDelay(acquisition_device[data_stream].Counters().CalculateDelay(frame, module_number)); - current_status.SetProgress(GetProgress()); - current_status.SetStatus(GetStatus()); - } - - uint64_t offset = experiment.GetFirstModuleOfDataStream(data_stream) + module_number; - if (!only_2nd_sc_pedestal) - offset += experiment.GetModulesNum() * storage_cell; - - if (!ignore) - *pedestal[offset] += pedestal_calc; - } catch (const JFJochException &e) { - Cancel(e); - } - logger.Debug("Pedestal calculation thread for data stream {} module {} storage cell {} -> header {} done", - data_stream, module_number, storage_cell, storage_cell_header); -} - -int64_t JFJochReceiverFPGA::SummationThread(uint16_t data_stream, - int64_t image_number, - uint16_t module_number, - uint32_t threadid, - ModuleSummation &summation) { +void JFJochReceiverFPGA::SummationThread(uint16_t data_stream, + int64_t image_number, + uint16_t module_number, + uint32_t threadid, + ModuleSummation &summation) { ModuleSummation local_summation(experiment); int64_t starting_frame = image_number * experiment.GetSummation(); @@ -317,7 +199,6 @@ int64_t JFJochReceiverFPGA::SummationThread(uint16_t data_stream, if (!summation.empty()) summation.AddFPGAOutput(local_summation.GetOutput(), 4); - return 0; } void JFJochReceiverFPGA::FrameTransformationThread(uint32_t threadid) { @@ -380,7 +261,7 @@ void JFJochReceiverFPGA::FrameTransformationThread(uint32_t threadid) { for (int i = 0; i < experiment.GetModulesNum(); i++) summation.emplace_back(std::make_unique(experiment)); - std::vector > futures; + std::vector> futures; for (int d = 0; d < ndatastreams; d++) { for (int m = 0; m < experiment.GetModulesNum(d); m++) { @@ -455,41 +336,6 @@ void JFJochReceiverFPGA::FrameTransformationThread(uint32_t threadid) { continue; } - message.image = CompressedImage(transformation.GetImage(), - experiment.GetPixelsNum() * experiment.GetByteDepthImage(), - experiment.GetXPixelsNum(), - experiment.GetYPixelsNum(), - experiment.GetImageMode(), - CompressionAlgorithm::NO_COMPRESSION); - - if (gpu_analysis) { - // Compressed here into a slot of the image buffer, where it waits for the GPU analysis; GPUSink - // writes it, with its analysis, to a second slot, which is sent. A frame that finds no slot - // free, or as many frames waiting as the analysis is to hold, is dropped, as the receiver drops - // any frame that finds the image buffer full. - ++images_collected; - uncompressed_size += experiment.GetModulesNum() * RAW_MODULE_SIZE * experiment.GetByteDepthImage(); - auto held = std::make_shared(); - held->slot = image_buffer.GetImageSlot(); - if (held->slot == nullptr) { - writer_queue_full = true; - continue; - } - const size_t size = transformation.CompressImage(static_cast(held->slot->GetImage()), - experiment.GetImageBufferLocationSize()); - held->message = std::move(message); - held->message.image = CompressedImage(held->slot->GetImage(), size, - experiment.GetXPixelsNum(), experiment.GetYPixelsNum(), - experiment.GetImageMode(), - experiment.GetCompressionAlgorithm()); - if (!gpu->Hold(held)) { - writer_queue_full = true; - continue; - } - compressed_size += size; - continue; - } - // No-op unless the CPU backend is forced; fills az_int_profile_image from the assembled image analyzer->RunAzimuthalIntegration(transformation.GetImage(), az_int_profile_image); @@ -616,12 +462,7 @@ void JFJochReceiverFPGA::FrameTransformationThread(uint32_t threadid) { } float JFJochReceiverFPGA::GetEfficiency() const { - - uint64_t expected_packets; - if (experiment.GetImageNum() == 0) - expected_packets = expected_packets_per_image * experiment.GetFrameNum(); - else - expected_packets = expected_packets_per_image * experiment.GetImageNum(); + uint64_t expected_packets = expected_packets_per_image * experiment.GetImageNum(); uint64_t received_packets = 0; for (int d = 0; d < ndatastreams; d++) { @@ -652,43 +493,29 @@ float JFJochReceiverFPGA::GetProgress() const { if (experiment.IsCPUSummation()) frames *= experiment.GetSummation(); - if (frames == 0) - frames = experiment.GetFrameNum(); - if ((frames == 0) || (acquisition_device[0].Counters().IsAcquisitionFinished())) + if (acquisition_device[0].Counters().IsAcquisitionFinished()) return 1.0; return static_cast(acquisition_device[0].Counters().GetSlowestFrameNumber()) / static_cast(frames); } +void JFJochReceiverFPGA::AddToEndMessage(EndMessage &message) { + AddIndexingToEndMessage(message, indexer); +} + void JFJochReceiverFPGA::FinalizeMeasurement() { - if (!frame_transformation_futures.empty()) { - for (auto &future: frame_transformation_futures) - future.get(); + for (auto &future: frame_transformation_futures) + future.get(); - logger.Debug("All processing threads done"); - } - - // Where the start message never went out (or the analysis could not be set up), there is no end - // message either: the devices are stopped all the same, and the error is the collection's result. - std::exception_ptr gpu_error; - if (gpu) { - try { - gpu->Finish(); - } catch (const std::exception &) { - gpu_error = std::current_exception(); - } - } + logger.Debug("All processing threads done"); current_status.SetProgress(1.0); current_status.SetStatus(GetStatus()); - if (!gpu_error) - SendEndMessage(); + SendEndMessage(); - if (experiment.GetImageNum() > 0) { - for (int d = 0; d < ndatastreams; d++) - acquisition_device[d].Cancel(); - } + for (int d = 0; d < ndatastreams; d++) + acquisition_device[d].Cancel(); end_time = std::chrono::system_clock::now(); @@ -702,18 +529,10 @@ void JFJochReceiverFPGA::FinalizeMeasurement() { throw JFJochException(JFJochExceptionCategory::ZeroMQ, "Send commands not finalized in " + std::to_string(SendFinalizeTimeout.count()) + " seconds"); } - if (gpu_error) { - current_status.SetProgress({}); - current_status.SetStatus(GetStatus()); - std::rethrow_exception(gpu_error); - } logger.Info("Receiving data done"); if (push_images_to_writer) writer_error = image_pusher.Finalize(); - // Last image -> all written, as the rugnux receiver reports it - if (gpu) - gpu->Written(); current_status.SetProgress({}); current_status.SetStatus(GetStatus()); @@ -758,29 +577,10 @@ JFJochReceiverOutput JFJochReceiverFPGA::GetFinalStatistics() const { ret.received_packets.push_back(acquisition_device[d].Counters().GetTotalPackets(m)); } } - RetrievePedestal(ret.pedestal_result); return ret; } -void JFJochReceiverFPGA::RetrievePedestal(std::vector &output) const { - time_t curr_time = std::chrono::system_clock::to_time_t(start_time); - for (const auto &pc: pedestal) { - JFModulePedestal mp; - if (experiment.GetDetectorMode() == DetectorMode::PedestalG0) - pc->Export(mp, PEDESTAL_G0_WRONG_GAIN_ALLOWED_COUNT); - else - pc->Export(mp); - mp.SetCollectionTime(curr_time); - output.emplace_back(std::move(mp)); - } -} - void JFJochReceiverFPGA::LoadCalibrationToFPGA(uint16_t data_stream) { - if (experiment.IsPedestalRun()) { - acquisition_device[data_stream].InitializeEmptyPixelMask(experiment); - return; // No calibration loaded for pedestal - } - if (calibration != nullptr) acquisition_device[data_stream].InitializeCalibration(experiment, *calibration); @@ -793,97 +593,3 @@ void JFJochReceiverFPGA::LoadCalibrationToFPGA(uint16_t data_stream) { // Initialize data processing acquisition_device[data_stream].InitializeDataProcessing(experiment, *az_int_mapping); } - -void JFJochReceiverFPGA::GPUSink(DataMessage &message, const AzimuthalIntegrationProfile &profile) { - try { - const auto status = image_buffer.GetSlotStatus(); - message.receiver_buf_available = status.available_slots; - message.receiver_buf_in_preparation = status.preparation_slots; - message.receiver_buf_in_sending = status.sending_slots; - if (message.image.GetCompressedSize() > 0) - message.compression_ratio = static_cast(experiment.GetPixelsNum() * experiment.GetByteDepthImage()) - / static_cast(message.image.GetCompressedSize()); - - if (message.image_collection_efficiency == 1.0f) { - saturated_pixels.Add(message.saturated_pixel_count); - error_pixels.Add(message.error_pixel_count); - if (message.roi.contains("beam")) { - roi_beam_npixel.Add(message.roi["beam"].pixels); - roi_beam_sum.Add(message.roi["beam"].sum); - } - } - - scan_result.Add(message); - - if (!serialmx_filter.ApplyFilter(message)) - ++images_skipped; - else if (auto loc = image_buffer.GetImageSlot(); loc == nullptr) - writer_queue_full = true; - else { - auto writer_buffer = (uint8_t *) loc->GetImage(); - CBORStream2Serializer serializer(writer_buffer, experiment.GetImageBufferLocationSize()); - if (JFJochReceiverLite::SerializeImageOrDrop(serializer, message, *loc, - experiment.GetImageBufferLocationSize(), logger)) { - loc->SetImageNumber(message.number); - loc->SetImageSize(serializer.GetBufferSize()); - loc->SetIndexed(message.indexing_result.value_or(false)); - loc->ReadyToSend(); - - if (zmq_preview_socket != nullptr) - zmq_preview_socket->SendImage(writer_buffer, serializer.GetBufferSize()); - if (zmq_metadata_socket != nullptr) - zmq_metadata_socket->AddDataMessage(message); - - if (push_images_to_writer) { - if (image_pusher.SendImage(*loc)) - ++images_sent; - } else - loc->release(); - UpdateMaxImageSent(message.number); - } - } - - plots.Add(message, profile); - current_status.SetProgress(GetProgress()); - current_status.SetStatus(GetStatus()); - } catch (const JFJochException &e) { - logger.ErrorException(e); - Cancel(e); - } catch (const std::exception &e) { - const JFJochException error(JFJochExceptionCategory::WrongDAQState, - fmt::format("Image {} not written - {}", message.number, e.what())); - logger.ErrorException(error); - Cancel(error); - } -} - -void JFJochReceiverFPGA::AddToEndMessage(EndMessage &message) { - AddIndexingToEndMessage(message, indexer); - if (!gpu) - return; - message.unit_cell = gpu->GetConsensusUnitCell(); - message.refined_beam_center_x = gpu->GetBeamX_pxl(); - message.refined_beam_center_y = gpu->GetBeamY_pxl(); - message.refined_detector_distance_mm = gpu->GetDetectorDistance_mm(); - // The merged data, for the writer to put beside the master file. - if (const auto &m = gpu->GetMerged(); m && gpu->GetMergeExperiment().GetUnitCell()) - message.merged = MergedMtzTable(m->merge.merged, *gpu->GetMergeExperiment().GetUnitCell(), - gpu->GetMergeExperiment(), OutputProvenance{}); - if (!message.merged) - return; - // Every pusher serialises END into a buffer of MESSAGE_SIZE_FOR_START_END, and an END that does not fit there - // fails the collection. So it is serialised here first, as JFJochReceiverRugnuxRotation does; one that does not fit - // goes without the merged data. - const auto scratch = std::make_unique_for_overwrite(MESSAGE_SIZE_FOR_START_END); - CBORStream2Serializer serializer(scratch.get(), MESSAGE_SIZE_FOR_START_END); - try { - serializer.SerializeSequenceEnd(message); - } catch (const JFJochException &e) { - const std::string text = fmt::format("the merged data do not fit in the end message ({} MiB) and are not " - "written", MESSAGE_SIZE_FOR_START_END / (1024 * 1024)); - logger.Error("GPU analysis: {} - {}", text, e.what()); - if (rugnux_status) - rugnux_status->Warning(text); - message.merged.reset(); - } -} diff --git a/receiver/JFJochReceiverFPGA.h b/receiver/JFJochReceiverFPGA.h index d5afc4c73..5186ad6fa 100644 --- a/receiver/JFJochReceiverFPGA.h +++ b/receiver/JFJochReceiverFPGA.h @@ -3,7 +3,6 @@ #pragma once -#include #include #include #include @@ -21,18 +20,14 @@ #include "../common/ImageBuffer.h" #include "../common/PixelMask.h" -#include "../image_analysis/spot_finding/StrongPixelSet.h" #include "../common/AzimuthalIntegrationMapping.h" #include "../common/AzimuthalIntegrationProfile.h" #include "../jungfrau/JFCalibration.h" #include "../common/ADUHistogram.h" -#include "../common/Plot.h" #include "../common/JFJochReceiverPlots.h" -#include "../preview/PreviewImage.h" #include "LossyFilter.h" #include "JFJochReceiverCurrentStatus.h" -#include "../jungfrau/JFPedestalCalc.h" #include "../preview/ZMQPreviewSocket.h" #include "../preview/ZMQMetadataSocket.h" #include "ImageMetadata.h" @@ -40,15 +35,12 @@ #include "../image_analysis/MXAnalysisAfterFPGA.h" #include "../common/MovingAverage.h" #include "JFJochReceiverOutput.h" -#include "StillsGPUAnalysisFPGA.h" class JFJochReceiverFPGA : public JFJochReceiver { const JFCalibration *calibration; IndexAndRefine indexer; - std::vector> pedestal; - std::vector roi_map; std::vector> frame_transformation_futures; @@ -62,11 +54,9 @@ class JFJochReceiverFPGA : public JFJochReceiver { uint16_t ndatastreams{0}; const int64_t frame_transformation_nthreads; - const int64_t pedestal_nthreads; const int64_t summation_nthreads; int64_t expected_packets_per_image; - bool only_2nd_sc_pedestal = false; // special mode used for pedestal G1/G2 with storage cells std::latch frame_transformation_ready; std::latch data_acquisition_ready; @@ -75,31 +65,18 @@ class JFJochReceiverFPGA : public JFJochReceiver { void LoadCalibrationToFPGA(uint16_t data_stream); void FrameTransformationThread(uint32_t threadid); - void MeasurePedestalThread(uint16_t data_stream, - uint16_t module_number, - uint16_t storage_cell, - uint32_t threadid, - bool ignore); - int64_t SummationThread(uint16_t data_stream, + void SummationThread(uint16_t data_stream, int64_t image_number, uint16_t module_number, uint32_t threadid, ModuleSummation &summation); void Cancel(const JFJochException &e) override; - void FinalizeMeasurement(); - - // Serial data with rugnux on: the converted frames are analysed on the GPU (StillsGPUAnalysisFPGA), and - // the start message waits for its pre-pass. - const bool gpu_analysis; - RugnuxLiveStatus *const rugnux_status; - std::unique_ptr gpu; - void GPUSink(DataMessage &message, const AzimuthalIntegrationProfile &profile); void AddToEndMessage(EndMessage &message) override; + void FinalizeMeasurement(); void SendCalibration(); void SendPedestal(const std::string &prefix, const std::vector &v, int gain, int sc); - void RetrievePedestal(std::vector &output) const; public: JFJochReceiverFPGA(const DiffractionExperiment& experiment, const PixelMask &pixel_mask, @@ -113,9 +90,7 @@ public: ImageBuffer &image_buffer, ZMQPreviewSocket *zmq_preview_socket, ZMQMetadataSocket *zmq_metadata_socket, - IndexerThreadPool *indexing_thread_pool, - bool gpu_analysis = false, - RugnuxLiveStatus *rugnux_status = nullptr); + IndexerThreadPool *indexing_thread_pool); ~JFJochReceiverFPGA(); JFJochReceiverFPGA(const JFJochReceiverFPGA &other) = delete; JFJochReceiverFPGA& operator=(const JFJochReceiverFPGA &other) = delete; diff --git a/receiver/JFJochReceiverPedestal.cpp b/receiver/JFJochReceiverPedestal.cpp new file mode 100644 index 000000000..e44a3b87d --- /dev/null +++ b/receiver/JFJochReceiverPedestal.cpp @@ -0,0 +1,242 @@ +// SPDX-FileCopyrightText: 2026 Filip Leonarski, Paul Scherrer Institute +// SPDX-License-Identifier: GPL-3.0-only + +#include "JFJochReceiverPedestal.h" + +JFJochReceiverPedestal::JFJochReceiverPedestal(const DiffractionExperiment &in_experiment, + const PixelMask &in_pixel_mask, + AcquisitionDeviceGroup &in_aq_device, + ImagePusher &in_image_sender, + Logger &in_logger, + const SpotFindingSettings &in_spot_finding_settings, + JFJochReceiverCurrentStatus &in_current_status, + JFJochReceiverPlots &in_plots, + ImageBuffer &in_send_buf_ctrl) + : JFJochReceiver(in_experiment, + in_send_buf_ctrl, + in_image_sender, + in_current_status, + in_plots, + in_spot_finding_settings, + in_logger, + in_pixel_mask), + acquisition_device(in_aq_device), + ndatastreams(experiment.GetDataStreamsNum()), + pedestal_nthreads((experiment.GetStorageCellNumber() > 2) ? 1 : 4), + data_acquisition_ready(ndatastreams) { + image_buffer.StartMeasurement(experiment); + + if (acquisition_device.size() < ndatastreams) + throw JFJochException(JFJochExceptionCategory::InputParameterInvalid, + "Number of acquisition devices has to match data streams"); + + expected_packets_per_image = 0; + for (int d = 0; d < ndatastreams; d++) { + acquisition_device[d].PrepareAction(experiment); + expected_packets_per_image += acquisition_device[d].Counters().GetExpectedPacketsPerImage(); + + logger.Debug("Acquisition device {} prepared", d); + } + + logger.Debug("Data acquisition devices ready"); + + switch (experiment.GetDetectorMode()) { + case DetectorMode::PedestalG1: + only_2nd_sc_pedestal = !experiment.IsFixedGainG1() && (experiment.GetStorageCellNumber() == 2); + break; + case DetectorMode::PedestalG2: + only_2nd_sc_pedestal = (experiment.GetStorageCellNumber() == 2); + break; + default: + only_2nd_sc_pedestal = false; + break; + } + + int64_t pedestal_count = (only_2nd_sc_pedestal) + ? experiment.GetModulesNum() + : experiment.GetModulesNum() * experiment.GetStorageCellNumber(); + for (int i = 0; i < pedestal_count; i++) + pedestal.emplace_back(std::make_unique(experiment)); + + for (int s = 0; s < experiment.GetStorageCellNumber(); s++) { + bool ignore = only_2nd_sc_pedestal && (s == 0); + for (int d = 0; d < ndatastreams; d++) + for (int m = 0; m < experiment.GetModulesNum(d); m++) + for (int n = 0; n < pedestal_nthreads; n++) + pedestal_futures.emplace_back(std::async(std::launch::async, + &JFJochReceiverPedestal::MeasurePedestalThread, + this, d, m, s, n, ignore)); + } + logger.Debug("Pedestal threads ready ({} threads/module*SC)", pedestal_nthreads); + + for (int d = 0; d < ndatastreams; d++) + data_acquisition_futures.emplace_back(std::async(std::launch::async, &JFJochReceiverPedestal::AcquireThread, + this, d)); + + data_acquisition_ready.wait(); + start_time = std::chrono::system_clock::now(); + measurement = std::async(std::launch::async, &JFJochReceiverPedestal::FinalizeMeasurement, this); + logger.Info("Receiving data started"); +} + +void JFJochReceiverPedestal::AcquireThread(uint16_t data_stream) { + try { + acquisition_device[data_stream].InitializeEmptyPixelMask(experiment); + logger.Debug("Device thread {} start action", data_stream); + acquisition_device[data_stream].StartAction(experiment); + } catch (const JFJochException &e) { + Cancel(e); + data_acquisition_ready.count_down(); + logger.ErrorException(e); + logger.Warning("Device thread {} done due to an error", data_stream); + return; + } + + data_acquisition_ready.count_down(); + + try { + logger.Debug("Device thread {} wait for action complete", data_stream); + acquisition_device[data_stream].WaitForActionComplete(); + } catch (const JFJochException &e) { + logger.ErrorException(e); + Cancel(e); + logger.ErrorException(e); + logger.Warning("Device thread {} done due to an error", data_stream); + return; + } + logger.Debug("Device thread {} done", data_stream); +} + +void JFJochReceiverPedestal::MeasurePedestalThread(uint16_t data_stream, uint16_t module_number, uint16_t storage_cell, + uint32_t threadid, bool ignore) { + JFPedestalCalc pedestal_calc(experiment); + + uint64_t starting_frame = storage_cell + threadid * experiment.GetStorageCellNumber(); + uint64_t frame_stride = experiment.GetStorageCellNumber() * pedestal_nthreads; + uint32_t storage_cell_header = UINT32_MAX; + + try { + for (size_t frame = starting_frame; frame < experiment.GetFrameNum(); frame += frame_stride) { + // Frame will be processed only if one already collects frame+2 + acquisition_device[data_stream].Counters().WaitForFrame(frame + 2, module_number); + if (acquisition_device[data_stream].Counters().IsFullModuleCollected(frame, module_number) && !ignore) { + auto output = acquisition_device[data_stream].GetDeviceOutput(frame, module_number); + // Partial packets will bring more problems, than benefit + pedestal_calc.AnalyzeImage((uint16_t *) output->pixels); + storage_cell_header = (output->module_statistics.debug >> 8) & 0xF; + } + acquisition_device[data_stream].FrameBufferRelease(frame, module_number); + + UpdateMaxDelay(acquisition_device[data_stream].Counters().CalculateDelay(frame, module_number)); + current_status.SetProgress(GetProgress()); + current_status.SetStatus(GetStatus()); + } + + uint64_t offset = experiment.GetFirstModuleOfDataStream(data_stream) + module_number; + if (!only_2nd_sc_pedestal) + offset += experiment.GetModulesNum() * storage_cell; + + if (!ignore) + *pedestal[offset] += pedestal_calc; + } catch (const JFJochException &e) { + Cancel(e); + } + logger.Debug("Pedestal calculation thread for data stream {} module {} storage cell {} -> header {} done", + data_stream, module_number, storage_cell, storage_cell_header); +} + +float JFJochReceiverPedestal::GetEfficiency() const { + uint64_t expected_packets = expected_packets_per_image * experiment.GetFrameNum(); + uint64_t received_packets = 0; + + for (int d = 0; d < ndatastreams; d++) { + received_packets += acquisition_device[d].Counters().GetTotalPackets(); + } + + if ((expected_packets == received_packets) || (expected_packets == 0)) + return 1.0; + return received_packets / static_cast(expected_packets); +} + +void JFJochReceiverPedestal::Cancel(bool silent) { + JFJochReceiver::Cancel(silent); + + for (int d = 0; d < ndatastreams; d++) + acquisition_device[d].Cancel(); +} + +void JFJochReceiverPedestal::Cancel(const JFJochException &e) { + JFJochReceiver::Cancel(e); + + for (int d = 0; d < ndatastreams; d++) + acquisition_device[d].Cancel(); +} + +float JFJochReceiverPedestal::GetProgress() const { + int64_t frames = experiment.GetFrameNum(); + if ((frames == 0) || (acquisition_device[0].Counters().IsAcquisitionFinished())) + return 1.0; + + return static_cast(acquisition_device[0].Counters().GetSlowestFrameNumber()) / static_cast(frames); +} + +void JFJochReceiverPedestal::FinalizeMeasurement() { + for (auto &future: pedestal_futures) + future.get(); + + logger.Debug("All processing threads done"); + + current_status.SetProgress(1.0); + current_status.SetStatus(GetStatus()); + + end_time = std::chrono::system_clock::now(); + + for (auto &future: data_acquisition_futures) + future.get(); + + logger.Debug("Devices stopped"); + logger.Info("Receiving data done"); + + current_status.SetProgress({}); + current_status.SetStatus(GetStatus()); +} + +void JFJochReceiverPedestal::StopReceiver() { + if (measurement.valid()) { + measurement.get(); + logger.Debug("Receiver stopped"); + } +} + +JFJochReceiverPedestal::~JFJochReceiverPedestal() { + try { + if (measurement.valid()) + measurement.get(); + } catch (const std::exception &e) { + logger.Error("ReceiverPedestal teardown failed: {}", e.what()); + } catch (...) { + logger.Error("ReceiverPedestal teardown failed with unknown exception"); + } +} + +JFJochReceiverOutput JFJochReceiverPedestal::GetFinalStatistics() const { + JFJochReceiverOutput ret = JFJochReceiver::GetFinalStatistics(); + for (int d = 0; d < ndatastreams; d++) { + for (int m = 0; m < acquisition_device[d].Counters().GetModuleNumber(); m++) { + ret.expected_packets.push_back(acquisition_device[d].Counters().GetTotalExpectedPacketsPerModule()); + ret.received_packets.push_back(acquisition_device[d].Counters().GetTotalPackets(m)); + } + } + + time_t curr_time = std::chrono::system_clock::to_time_t(start_time); + for (const auto &pc: pedestal) { + JFModulePedestal mp; + if (experiment.GetDetectorMode() == DetectorMode::PedestalG0) + pc->Export(mp, PEDESTAL_G0_WRONG_GAIN_ALLOWED_COUNT); + else + pc->Export(mp); + mp.SetCollectionTime(curr_time); + ret.pedestal_result.emplace_back(std::move(mp)); + } + return ret; +} diff --git a/receiver/JFJochReceiverPedestal.h b/receiver/JFJochReceiverPedestal.h new file mode 100644 index 000000000..af423ec70 --- /dev/null +++ b/receiver/JFJochReceiverPedestal.h @@ -0,0 +1,63 @@ +// SPDX-FileCopyrightText: 2026 Filip Leonarski, Paul Scherrer Institute +// SPDX-License-Identifier: GPL-3.0-only + +#pragma once + +#include +#include +#include +#include + +#include "JFJochReceiver.h" +#include "../acquisition_device/AcquisitionDeviceGroup.h" +#include "../jungfrau/JFPedestalCalc.h" + +// A pedestal run: raw frames from the devices go into JFPedestalCalc; no image buffer slots, nothing goes out on any socket +class JFJochReceiverPedestal : public JFJochReceiver { + std::vector> pedestal; + + std::vector> pedestal_futures; + std::vector> data_acquisition_futures; + + std::future measurement; + + AcquisitionDeviceGroup &acquisition_device; + uint16_t ndatastreams{0}; + + const int64_t pedestal_nthreads; + + int64_t expected_packets_per_image; + bool only_2nd_sc_pedestal = false; // special mode used for pedestal G1/G2 with storage cells + + std::latch data_acquisition_ready; + + void AcquireThread(uint16_t data_stream); + void MeasurePedestalThread(uint16_t data_stream, + uint16_t module_number, + uint16_t storage_cell, + uint32_t threadid, + bool ignore); + void Cancel(const JFJochException &e) override; + void FinalizeMeasurement(); +public: + JFJochReceiverPedestal(const DiffractionExperiment &experiment, + const PixelMask &pixel_mask, + AcquisitionDeviceGroup &acquisition_devices, + ImagePusher &image_pusher, + Logger &logger, + const SpotFindingSettings &spot_finding_settings, + JFJochReceiverCurrentStatus ¤t_status, + JFJochReceiverPlots &plots, + ImageBuffer &image_buffer); + ~JFJochReceiverPedestal() override; + JFJochReceiverPedestal(const JFJochReceiverPedestal &other) = delete; + JFJochReceiverPedestal &operator=(const JFJochReceiverPedestal &other) = delete; + + void StopReceiver() override; + + float GetEfficiency() const override; + void Cancel(bool silent) override; + float GetProgress() const override; + + JFJochReceiverOutput GetFinalStatistics() const override; +}; diff --git a/receiver/JFJochReceiverService.cpp b/receiver/JFJochReceiverService.cpp index 54a6eb618..378b8a722 100644 --- a/receiver/JFJochReceiverService.cpp +++ b/receiver/JFJochReceiverService.cpp @@ -9,6 +9,7 @@ #include "JFJochReceiverFPGA.h" #include "JFJochReceiverLite.h" #include "JFJochReceiverDarkMask.h" +#include "JFJochReceiverPedestal.h" #include "../preview/JFJochJPEG.h" #include "../preview/JFJochTIFF.h" @@ -38,16 +39,16 @@ JFJochReceiverService &JFJochReceiverService::RugnuxLive(bool enable, std::share return *this; } -JFJochReceiverService &JFJochReceiverService::UseFPGAImagePuller(FPGAImagePullerUse use, size_t slots, bool blocking, - double frame_rate_hz) { +JFJochReceiverService &JFJochReceiverService::FPGAImagePullerSettings(size_t slots, bool blocking, double frame_rate_hz, + bool always) { std::unique_lock ul_state(state_mutex); if (state != ReceiverState::Idle) throw JFJochException(JFJochExceptionCategory::WrongDAQState, "Cannot change the receiver path during data collection"); - fpga_image_puller = use; fpga_image_puller_slots = slots; fpga_image_puller_blocking = blocking; fpga_image_puller_rate_hz = frame_rate_hz; + fpga_image_puller_always = always; return *this; } @@ -56,19 +57,12 @@ double JFJochReceiverService::GetFPGAImagePullerSlotWaitTime_s() const { return fpga_puller ? fpga_puller->GetSlotWaitTime_s() : 0.0; } -// Pedestal runs and summation on the host need JFJochReceiverFPGA +// A PSI collection analysed by rugnux live; summation on the host needs JFJochReceiverFPGA bool JFJochReceiverService::FPGAImagePullerFor(const DiffractionExperiment &experiment) const { if ((experiment.GetDetectorType() == DetectorType::DECTRIS) || experiment.IsPedestalRun() || experiment.IsCPUSummation() || (experiment.GetImageNum() <= 0)) return false; - switch (fpga_image_puller) { - case FPGAImagePullerUse::Always: - return true; - case FPGAImagePullerUse::RugnuxLive: - return rugnux_enable && (experiment.GetDetectorMode() == DetectorMode::Standard); - default: - return false; - } + return fpga_image_puller_always || (rugnux_enable && (experiment.GetDetectorMode() == DetectorMode::Standard)); } RugnuxLiveSnapshot JFJochReceiverService::GetRugnuxStatus() const { @@ -155,7 +149,15 @@ void JFJochReceiverService::Start(const DiffractionExperiment &experiment, puller = fpga_puller; } - if ((experiment.GetDetectorType() != DetectorType::DECTRIS) && !fpga_puller) { + if ((experiment.GetDetectorType() != DetectorType::DECTRIS) && experiment.IsPedestalRun()) { + receiver = std::make_unique(experiment, pixel_mask, aq_devices, image_pusher, + logger, spot_finding_settings, receiver_status, + plots, image_buffer); + } else if ((experiment.GetDetectorType() != DetectorType::DECTRIS) && !fpga_puller) { + if (rugnux_enable && experiment.IsCPUSummation()) { + analysis_warning = "no rugnux analysis: summation on the host"; + logger.Warning("{}", analysis_warning); + } // Summation on the host runs threads of its own for each image auto fpga_nthreads = nthreads; if (experiment.IsCPUSummation()) @@ -171,11 +173,7 @@ void JFJochReceiverService::Start(const DiffractionExperiment &experiment, image_buffer, zmq_preview_socket.get(), zmq_metadata_socket.get(), - indexer_thread_pool.get(), - // Serial data with rugnux on: the frames are - // analysed on the GPU, after a pre-pass. - rugnux_enable && !RugnuxRotationData(experiment), - &rugnux_status); + indexer_thread_pool.get()); } else { if (puller) image_puller = puller; diff --git a/receiver/JFJochReceiverService.h b/receiver/JFJochReceiverService.h index c8a6a7f65..2590a30fc 100644 --- a/receiver/JFJochReceiverService.h +++ b/receiver/JFJochReceiverService.h @@ -20,9 +20,6 @@ struct RugnuxModel; -// RugnuxLive: collections analysed by rugnux live; Always: also the others, through JFJochReceiverLite; -// Never: all on JFJochReceiverFPGA, its own live stills included -enum class FPGAImagePullerUse { RugnuxLive, Always, Never }; class JFJochReceiverService { std::unique_ptr receiver; @@ -43,8 +40,8 @@ class JFJochReceiverService { RugnuxLiveStatus rugnux_status; // of the last collection, kept after it ends std::string analysis_warning; // why the collection was not analysed as asked, for the broker's status - // Which PSI collections go through FPGAImagePuller and the stream receivers - FPGAImagePullerUse fpga_image_puller = FPGAImagePullerUse::RugnuxLive; + // A PSI collection analysed by rugnux live goes through FPGAImagePuller to the stream receivers + bool fpga_image_puller_always = false; size_t fpga_image_puller_slots = FPGAImagePuller::DefaultSlots; bool fpga_image_puller_blocking = false; double fpga_image_puller_rate_hz = 0; @@ -77,9 +74,11 @@ public: double deadline_s, bool refine_solvent = false, bool force_still = false); RugnuxLiveSnapshot GetRugnuxStatus() const; void ClearRugnuxStatus(); // back to Idle, as before any collection - // blocking, frame_rate_hz: see FPGAImagePuller - JFJochReceiverService& UseFPGAImagePuller(FPGAImagePullerUse use, size_t slots = FPGAImagePuller::DefaultSlots, - bool blocking = false, double frame_rate_hz = 0); + // slots, blocking, frame_rate_hz: see FPGAImagePuller. always: every PSI collection but pedestal and host + // summation through the puller, without rugnux to JFJochReceiverLite (for tests comparing it with + // JFJochReceiverFPGA) + JFJochReceiverService& FPGAImagePullerSettings(size_t slots = FPGAImagePuller::DefaultSlots, bool blocking = false, + double frame_rate_hz = 0, bool always = false); // Of the last collection through FPGAImagePuller: FPGAImagePuller::GetSlotWaitTime_s, 0 without one double GetFPGAImagePullerSlotWaitTime_s() const; JFJochReceiverService& PreviewSocket(const std::string &addr, const std::optional &watermark = {}); diff --git a/receiver/StillsGPUAnalysisFPGA.cpp b/receiver/StillsGPUAnalysisFPGA.cpp deleted file mode 100644 index 41b4dc7c0..000000000 --- a/receiver/StillsGPUAnalysisFPGA.cpp +++ /dev/null @@ -1,419 +0,0 @@ -// SPDX-FileCopyrightText: 2026 Filip Leonarski, Paul Scherrer Institute -// SPDX-License-Identifier: GPL-3.0-only - -#include "StillsGPUAnalysisFPGA.h" - -#include - -#include "../common/CUDAWrapper.h" -#include "../common/ThreadAffinity.h" -#include "../image_analysis/MXAnalysisWithoutFPGA.h" -#include "../rugnux/RugnuxDefaults.h" - -StillsGPUAnalysisFPGA::StillsGPUAnalysisFPGA(const DiffractionExperiment &in_experiment, const PixelMask &in_mask, - const StartMessage &in_start, IndexerThreadPool *in_indexing_thread_pool, - int64_t nthreads, int64_t in_max_held, Logger &in_logger, Ready in_ready, - Sink in_sink, Settings in_settings, Failed in_failed, - RugnuxLiveStatus *in_status, bool in_merge) - : experiment(in_experiment), mask(in_mask), start(in_start), indexing_thread_pool(in_indexing_thread_pool), - logger(in_logger), ready(std::move(in_ready)), sink(std::move(in_sink)), settings(std::move(in_settings)), - setup_failed(std::move(in_failed)), status(in_status), merge_frames(in_merge), - max_held(std::max(1, in_max_held)), queue(max_held) { - live.images_needed = std::min(PREPASS_IMAGES, experiment.GetImageNum()); - live.file_beam_x_pxl = experiment.GetBeamX_pxl(); - live.file_beam_y_pxl = experiment.GetBeamY_pxl(); - live.file_distance_mm = experiment.GetDetectorDistance_mm(); - if (status) { - status->Start(experiment.GetImageNum(), - static_cast(experiment.GetImageNum()) - * std::chrono::duration(experiment.GetImageTime()).count(), - std::chrono::steady_clock::now()); - status->Step("Pre-pass"); - Publish(); - } - prepass_future = std::async(std::launch::async, &StillsGPUAnalysisFPGA::PrePassThread, this); - for (int64_t i = 0; i < nthreads; i++) - analysis_futures.emplace_back(std::async(std::launch::async, &StillsGPUAnalysisFPGA::AnalysisThread, this)); - logger.Info("GPU analysis: {} threads, at least the first {} images held for the pre-pass", nthreads, PREPASS_IMAGES); -} - -StillsGPUAnalysisFPGA::~StillsGPUAnalysisFPGA() { - try { - if (!finished) - Finish(); - } catch (const std::exception &e) { - logger.Error("GPU analysis: {}", e.what()); - } - if (status && outcome) - status->Finish(outcome->first, outcome->second); -} - -void StillsGPUAnalysisFPGA::AnalysisError(const std::string &text) { - logger.Error("GPU analysis: {}", text); - std::unique_lock ul(error_mutex); - if (analysis_error.empty()) - analysis_error = text; -} - -void StillsGPUAnalysisFPGA::Publish() { - std::unique_lock ul(live_mutex); - if (live.prepass == RugnuxLivePrePass::Done || live.prepass == RugnuxLivePrePass::Failed) { - const double t = std::chrono::duration(std::chrono::steady_clock::now() - ready_time).count(); - if (t > 0 && live.images_analysed > 0) - live.analysis_rate_hz = static_cast(live.images_analysed) / t; - } - status->Stills(live); -} - -bool StillsGPUAnalysisFPGA::Hold(const std::shared_ptr &image) { - if (status) - status->ImageReceived(std::chrono::steady_clock::now()); - if (!queue.Put(image)) { - // As many frames wait as the buffer is to hold: the pre-pass runs on what it has, for the last time. - StartPrePass(); - return false; - } - { - std::unique_lock ul(prepass_mutex); - if (!prepass_over) { - prepass_images[image->message.number] = image; - std::unique_lock ul_live(live_mutex); - live.images_held = static_cast(prepass_images.size()); - } - } - prepass_cv.notify_all(); - if (status) - Publish(); - return true; -} - -void StillsGPUAnalysisFPGA::StartPrePass() { - { - std::unique_lock ul(prepass_mutex); - prepass_last = true; - } - prepass_cv.notify_all(); -} - -void StillsGPUAnalysisFPGA::Finish() { - finished = true; - StartPrePass(); - prepass_future.get(); - for (size_t i = 0; i < analysis_futures.size(); i++) - queue.PutBlocking(nullptr); - for (auto &f: analysis_futures) - f.get(); - if (status) { - last_image = status->LastImage(); - Publish(); - } - if (merge_future.valid()) { - if (status) - status->Step("Merge"); - merge_queue.Put(-1); - merge_future.get(); - if (merged && status) { - PublishMerge(*merged, "the collection"); - status->Headline(merge_experiment.GetSpaceGroupOrP1().xhm(), merged->merge.statistics.overall.d_min, - std::nullopt); - } - } - if (status) { - if (setup_error) - status->Finish(RugnuxLiveState::Failed, "GPU analysis setup failed"); - else { - // Reported by Written, once everything is written - the end message and the writer go on meanwhile. - status->Step("Writing"); - std::unique_lock ul(error_mutex); - if (analysis_error.empty()) - outcome.emplace(RugnuxLiveState::Done, ""); - else - outcome.emplace(RugnuxLiveState::Failed, analysis_error); - } - } - if (setup_error) - std::rethrow_exception(setup_error); -} - -void StillsGPUAnalysisFPGA::Written() { - if (!status || !outcome) - return; - if (last_image) - status->Latency(std::chrono::duration(std::chrono::steady_clock::now() - last_image.value()).count()); - status->Finish(outcome->first, outcome->second); - outcome.reset(); -} - -void StillsGPUAnalysisFPGA::PrePassThread() { - const auto masked = [](const PixelMask &m) { - return std::count_if(m.GetMask().begin(), m.GetMask().end(), [](uint32_t v) { return v != 0; }); - }; - setup.experiment = experiment; - setup.mask = mask; - const int64_t all_images = experiment.GetImageNum(); - std::optional result; - std::chrono::steady_clock::time_point prepass_start = std::chrono::steady_clock::now(); - // At a low hit rate the first frames may not be enough to fit the geometry on, or may not hold a crystal: with - // a cell to fit, the pre-pass runs again on all that is held once that has doubled, until the fit has its - // frames, or the collection ended, or the sample is as large as it may grow (the last try): bounded so that - // the last run is short and the other half of the queue takes the frames arriving meanwhile. - const int64_t max_sample = std::min(PREPASS_MAX_IMAGES, max_held / 2); - for (int64_t needed = std::min(PREPASS_IMAGES, all_images); ;) { - std::map> sample; - bool last; - { - std::unique_lock ul(prepass_mutex); - prepass_cv.wait(ul, [&] { - return prepass_last || static_cast(prepass_images.size()) >= needed; - }); - // Frames that arrived during the previous run do not make this one larger than the bound. - for (const auto &[n, image]: prepass_images) { - if (static_cast(sample.size()) >= std::max(needed, max_sample)) - break; - sample.emplace(n, image); - } - last = prepass_last || static_cast(sample.size()) >= std::min(all_images, max_sample); - } - if (sample.empty()) - break; - { - std::unique_lock ul(live_mutex); - live.prepass = RugnuxLivePrePass::Running; - } - if (status) - Publish(); - try { - const auto t0 = std::chrono::steady_clock::now(); - auto r = RunStillsPrePass(start, sample, static_cast(std::thread::hardware_concurrency())); - logger.Info("Pre-pass on {} images ({:.1f} s): beam centre ({:.2f}, {:.2f}) -> ({:.2f}, {:.2f}) px, " - "distance {:.2f} -> {:.2f} mm on {} frames, masked pixels {} -> {}", r.images, - std::chrono::duration(std::chrono::steady_clock::now() - t0).count(), - experiment.GetBeamX_pxl(), experiment.GetBeamY_pxl(), r.beam_x_pxl, r.beam_y_pxl, - experiment.GetDetectorDistance_mm(), r.distance_mm, r.geometry_frames, - masked(mask), masked(r.mask)); - result = std::move(r); - } catch (const std::exception &e) { - logger.Warning("Pre-pass on {} images failed - {}", sample.size(), e.what()); - } - if (last || !experiment.GetUnitCell() - || (result && result->geometry_frames >= RUGNUX_REFINE_GEOMETRY_FRAMES)) - break; - needed = std::min({2 * static_cast(sample.size()), all_images, max_sample}); - std::unique_lock ul(live_mutex); - live.prepass = RugnuxLivePrePass::Holding; - live.images_needed = needed; - } - { - // The frames are analysed from here on: their slots go back to the buffer once they are sent. - std::unique_lock ul(prepass_mutex); - prepass_over = true; - prepass_images.clear(); - } - const bool failed = !result; - int geometry_frames = 0; - if (result) { - const auto &r = *result; - setup.experiment.BeamX_pxl(r.beam_x_pxl).BeamY_pxl(r.beam_y_pxl).DetectorDistance_mm(r.distance_mm); - setup.mask = r.mask; - geometry_frames = r.geometry_frames; - const auto &m = r.mask.GetMask(); - std::unique_lock ul(live_mutex); - live.beam_x_pxl = r.beam_x_pxl; - live.beam_y_pxl = r.beam_y_pxl; - live.distance_mm = r.distance_mm; - live.shadow_pixels = std::count_if(m.begin(), m.end(), [](uint32_t v) { - return (v & (1u << PixelMask::BeamStopPixelBit)) != 0; - }); - live.bad_pixels = std::count_if(m.begin(), m.end(), [](uint32_t v) { - return (v & (1u << PixelMask::HotPixelBit)) != 0; - }); - } else - logger.Warning("Pre-pass failed, the images are analysed with the stated beam centre and mask"); - try { - setup.mapping = std::make_unique(setup.experiment, setup.mask); - // Retained for the merge, which takes each image's reflections as soon as it is analysed. - indexer = std::make_unique(setup.experiment, indexing_thread_pool, merge_frames, true); - if (geometry_frames == 0) { - const std::string text = fmt::format( - "The pre-pass could not refine the geometry (too few frames indexed in what the buffer holds, or no unit cell given): the " - "whole run is analysed at the distance in the header, {:.2f} mm, beam centre ({:.2f}, {:.2f}) px", - setup.experiment.GetDetectorDistance_mm(), setup.experiment.GetBeamX_pxl(), - setup.experiment.GetBeamY_pxl()); - logger.Warning("{}", text); - if (status) - status->Note(text); - } - if (merge_frames) { - merge_experiment = setup.experiment; - merge_experiment.ImportScalingSettings(RugnuxDefaultScalingSettings(false)); - merge = std::make_unique(merge_experiment, experiment.GetImageNum(), - setup.experiment.GetUnitCell(), std::nullopt, - setup.experiment.IsDetectIceRings(), - SpotFindingSettings().ice_ring_width_Q_recipA, logger); - merge_future = std::async(std::launch::async, &StillsGPUAnalysisFPGA::MergeThread, this); - } - ready(setup); - } catch (const std::exception &e) { - // Nothing can be written without the start message: the frames are dropped (AnalysisThread), and - // the collection is stopped. - const auto *j = dynamic_cast(&e); - const JFJochException error = j ? *j : JFJochException(JFJochExceptionCategory::WrongDAQState, - std::string("GPU analysis setup failed: ") + e.what()); - logger.ErrorException(error); - setup_error = j ? std::current_exception() : std::make_exception_ptr(error); - if (setup_failed) - setup_failed(error); - prepass_done.count_down(); - return; - } - { - std::unique_lock ul(live_mutex); - live.prepass = failed ? RugnuxLivePrePass::Failed : RugnuxLivePrePass::Done; - live.prepass_s = std::chrono::duration(std::chrono::steady_clock::now() - prepass_start).count(); - ready_time = std::chrono::steady_clock::now(); - } - if (status) { - status->Step("GPU analysis"); - Publish(); - } - prepass_done.count_down(); -} - -void StillsGPUAnalysisFPGA::AnalysisThread() { - try { - pin_gpu(); - } catch (const std::exception &e) { - logger.Warning("Error pinning GPU {}", e.what()); - } - - prepass_done.wait(); - - if (setup_error) { - while (queue.GetBlocking()) {} - return; - } - - // A thread whose analysis cannot be built still passes its frames on, unanalysed. - std::unique_ptr analysis; - try { - analysis = std::make_unique(setup.experiment, *setup.mapping, setup.mask, - *indexer, /*enable_fused_adaptive_gpu=*/true); - } catch (const std::exception &e) { - AnalysisError(std::string("analysis thread could not start, its frames are written unanalysed - ") - + e.what()); - } - - while (auto held = queue.GetBlocking()) { - DataMessage &message = held->message; - std::optional profile; - const auto start_time = std::chrono::steady_clock::now(); - profile.emplace(*setup.mapping); - try { - if (analysis) - analysis->Analyze(message, *profile, settings()); - } catch (const JFJochException &e) { - // The frame is still written, without its analysis. - logger.ErrorException(e); - } catch (const std::exception &e) { - AnalysisError(fmt::format("image {} written unanalysed - {}", message.number, e.what())); - } - message.processing_time_s = std::chrono::duration(std::chrono::steady_clock::now() - - start_time).count(); - try { - sink(message, *profile); - if (merge) - merge_queue.Put(message.number); - if (status) { - int64_t analysed; - { - std::unique_lock ul(live_mutex); - analysed = ++live.images_analysed; - if (message.indexing_result.value_or(false)) - ++live.images_indexed; - } - status->Progress(analysed, experiment.GetImageNum()); - Publish(); - } - } catch (const std::exception &e) { - // The thread goes on with the next frame, so that the queue is drained. - AnalysisError(fmt::format("image {} lost - {}", message.number, e.what())); - } - } -} - -std::optional StillsGPUAnalysisFPGA::GetConsensusUnitCell() const { - return indexer->GetConsensusUnitCell(); -} - -float StillsGPUAnalysisFPGA::GetBeamX_pxl() const { - return setup.experiment.GetBeamX_pxl(); -} - -float StillsGPUAnalysisFPGA::GetBeamY_pxl() const { - return setup.experiment.GetBeamY_pxl(); -} - -float StillsGPUAnalysisFPGA::GetDetectorDistance_mm() const { - return setup.experiment.GetDetectorDistance_mm(); -} - -const std::optional &StillsGPUAnalysisFPGA::GetMerged() const { - return merged; -} - -const DiffractionExperiment &StillsGPUAnalysisFPGA::GetMergeExperiment() const { - return merge_experiment; -} - -void StillsGPUAnalysisFPGA::MergeThread() { - constexpr int64_t PREPARE_EVERY = 200; // frames between two Prepare calls after a checkpoint - const int64_t images = experiment.GetImageNum(); - // The cell merged in, as rugnux merges it: the consensus of the frames indexed by the first merge (the - // collection's cell only picks the frames that are merged). - bool cell_set = false; - const auto have_cell = [&] { - if (!cell_set) - if (const auto c = indexer->GetConsensusUnitCell()) { - merge_experiment.SetUnitCell(*c); - merge->Cell(*c); - cell_set = true; - } - return cell_set; - }; - size_t next = 0; - try { - const auto add = [&](int64_t n, IntegrationOutcome &&o) { - merge->Add(n, std::move(o)); - if (next < CHECKPOINTS.size() - && merge->Added() >= std::llround(CHECKPOINTS[next] * static_cast(images))) { - if (have_cell()) - PublishMerge(merge->Checkpoint(MERGE_THREADS), - fmt::format("{:.0f}% of the images (provisional)", 100.0 * CHECKPOINTS[next])); - ++next; - } else if (next > 0 && merge->Added() % PREPARE_EVERY == 0) - merge->Prepare(MERGE_THREADS); - }; - for (int64_t n = merge_queue.GetBlocking(); n >= 0; n = merge_queue.GetBlocking()) - add(n, indexer->TakeIntegrationOutcome(n)); - if (have_cell()) { - merged = merge->Final(static_cast(AvailableCpus())); - logger.Info("Stills merge after the last image: {:.2f} s", merged->seconds); - } - } catch (const std::exception &e) { - logger.Warning("Stills merge failed: {}", e.what()); - merged.reset(); - } -} - -void StillsGPUAnalysisFPGA::PublishMerge(const StillsMergeOutput &out, const std::string &title) { - const auto &o = out.merge.statistics.overall; - const std::string text = fmt::format("Merge of {}: {} crystals, {:.2f} A, CC1/2 {:.3f}, R_split {:.3f}, " - "completeness {:.1f}%, {:.1f} ({:.1f} s)", title, out.images, - o.d_min, o.cc_half, o.r_split, - o.possible_unique_reflections > 0 - ? 100.0 * o.unique_reflections / o.possible_unique_reflections : 0.0, - o.mean_i_over_sigma, out.seconds); - logger.Info("{}", text); - if (status) - status->Note(text); -} diff --git a/receiver/StillsGPUAnalysisFPGA.h b/receiver/StillsGPUAnalysisFPGA.h deleted file mode 100644 index 0773af0af..000000000 --- a/receiver/StillsGPUAnalysisFPGA.h +++ /dev/null @@ -1,151 +0,0 @@ -// SPDX-FileCopyrightText: 2026 Filip Leonarski, Paul Scherrer Institute -// SPDX-License-Identifier: GPL-3.0-only - -#pragma once - -#include -#include -#include -#include -#include -#include -#include -#include -#include -#include - -#include "StillsPrePass.h" -#include "RugnuxLiveStatus.h" -#include "../common/DiffractionExperiment.h" -#include "../common/JFJochException.h" -#include "../common/AzimuthalIntegrationMapping.h" -#include "../common/AzimuthalIntegrationProfile.h" -#include "../common/Logger.h" -#include "../common/ThreadSafeFIFO.h" -#include "../image_analysis/IndexAndRefine.h" -#include "../rugnux/StillsLiveMerge.h" - -// JFJochReceiverFPGA's live stills, kept as they are at rc.185 while the stream receivers take StillsGPUAnalysis. -// Serial frames analysed on the GPU as the DECTRIS ones are (MXAnalysisWithoutFPGA), after a pre-pass on -// the first PREPASS_IMAGES (RunStillsPrePass) has decided the beam centre and the mask they are analysed -// with. Every frame given before the pre-pass is done is held; `ready` is called once it is, with the -// geometry and mask the frames are then analysed at, before any of them is analysed; `sink` gets each -// frame once analysed, from one of the analysis threads. Where `status` is given, the run is reported there -// (pre-pass, its decisions, the analysis). -// At most `max_held` frames wait for analysis: Hold refuses one more, so the slots held stay bounded. -// Where the setup after the pre-pass fails (`ready` included), `failed` is called at once, the frames are -// dropped unanalysed and Finish throws the error. An analysis thread that fails passes its frames on -// unanalysed, and the run is reported as failed. -// The indexed frames are merged as `rugnux --mode scale` merges them (StillsLiveMerge), beside the analysis: -// a provisional merge at each of CHECKPOINTS of the images, on MERGE_THREADS threads, reported as a step -// of the status, and the merge of the whole collection once the last frame is analysed, on every thread, -// before Finish returns (GetMerged). The cell is the run's consensus at the first merge, as rugnux merges in -// it (the collection's cell picks the frames merged); the space group the collection's, else P1. -// merge = false leaves it out. -// With a cell given, the pre-pass runs again on all the frames held each time they have doubled, until the geometry -// fit has its frames, the collection ends or the sample reaches PREPASS_MAX_IMAGES or half of `max_held`; the -// analysis starts after that and catches up from the frames held. The bound keeps the last run short and leaves -// room in the queue for the frames arriving meanwhile, which are otherwise not written. The geometry is fixed when the pre-pass ends: every frame is analysed and merged at it. Where the pre-pass could -// not refine it (too few of the frames it had indexed: a small image buffer, a serial hit rate, a chip whose first -// frames are empty; or no cell given), the header's distance stays for the whole run, with a warning in the log -// and the status. -class StillsGPUAnalysisFPGA { -public: - // Enough frames for the distance to be refined at a serial hit rate: of 100 frames of a collection indexed - // at 18%, 7 indexed at a distance 2.6% off and the geometry refinement did not run; of 500, 34 did and - // refined it to 0.4%. They wait in the image buffer, which has to hold them in half its slots. - constexpr static int64_t PREPASS_IMAGES = 500; - constexpr static int64_t PREPASS_MAX_IMAGES = 4 * PREPASS_IMAGES; - constexpr static std::array CHECKPOINTS = {0.5, 0.75}; - constexpr static int MERGE_THREADS = 8; - - struct Setup { - DiffractionExperiment experiment; - PixelMask mask; - std::unique_ptr mapping; - }; - using Ready = std::function; - using Sink = std::function; - using Settings = std::function; - using Failed = std::function; - - // `start`: the collection's start message, as it would be sent without the pre-pass. - StillsGPUAnalysisFPGA(const DiffractionExperiment &experiment, const PixelMask &mask, const StartMessage &start, - IndexerThreadPool *indexing_thread_pool, int64_t nthreads, int64_t max_held, Logger &logger, - Ready ready, Sink sink, Settings settings, Failed failed = {}, - RugnuxLiveStatus *status = nullptr, bool merge = true); - ~StillsGPUAnalysisFPGA(); - - // False where `max_held` frames already wait: the frame is not taken. - bool Hold(const std::shared_ptr &image); - // No frame comes after this: the pre-pass runs on what came, if it has not, and every frame is - // analysed before it returns. Throws where the setup after the pre-pass failed. - void Finish(); - // After Finish, once the end message is out and the writer is done: the status gets the latency from the last - // image and then the run's outcome. Without it the outcome is reported when the analysis goes, with no latency. - void Written(); - - // After Finish. - [[nodiscard]] std::optional GetConsensusUnitCell() const; - [[nodiscard]] float GetBeamX_pxl() const; - [[nodiscard]] float GetBeamY_pxl() const; - [[nodiscard]] float GetDetectorDistance_mm() const; - // The merge of the collection, where one was made. - [[nodiscard]] const std::optional &GetMerged() const; - [[nodiscard]] const DiffractionExperiment &GetMergeExperiment() const; - -private: - const DiffractionExperiment &experiment; - const PixelMask &mask; - const StartMessage start; - IndexerThreadPool *indexing_thread_pool; - Logger &logger; - Ready ready; - Sink sink; - Settings settings; - Failed setup_failed; - RugnuxLiveStatus *status; - const bool merge_frames; - - std::mutex live_mutex; - RugnuxLiveStills live; - std::chrono::steady_clock::time_point ready_time; - void Publish(); - // Kept by Finish for Written - std::optional last_image; - std::optional> outcome; - - Setup setup; - std::unique_ptr indexer; - - std::mutex prepass_mutex; - std::condition_variable prepass_cv; - bool prepass_last = false; // what is held is all there will be - bool prepass_over = false; - std::map> prepass_images; - std::latch prepass_done{1}; - std::exception_ptr setup_error; // set before prepass_done - - std::mutex error_mutex; - std::string analysis_error; // the first, where an analysis thread failed - void AnalysisError(const std::string &text); - - const int64_t max_held; - ThreadSafeFIFO> queue; - std::future prepass_future; - std::vector> analysis_futures; - bool finished = false; - - // The frames analysed, by number, for the merge (-1 after the last); it takes their outcomes from the indexer. - ThreadSafeFIFO merge_queue; - std::unique_ptr merge; // after the indexer: its reflections are in the indexer's arena - DiffractionExperiment merge_experiment; - std::optional merged; - std::future merge_future; - - void StartPrePass(); - void PrePassThread(); - void AnalysisThread(); - void MergeThread(); - void PublishMerge(const StillsMergeOutput &out, const std::string &title); -}; diff --git a/tests/CMakeLists.txt b/tests/CMakeLists.txt index f30cb28c6..d120fcab0 100644 --- a/tests/CMakeLists.txt +++ b/tests/CMakeLists.txt @@ -132,7 +132,6 @@ ADD_EXECUTABLE(jfjoch_test RugnuxLiveTriageTest.cpp RugnuxScaleInputsTest.cpp StillsGPUAnalysisTest.cpp - StillsGPUAnalysisFPGATest.cpp RugnuxStructureTest.cpp SweepLayoutTest.cpp BrukerReaderTest.cpp diff --git a/tests/FPGAImagePullerTest.cpp b/tests/FPGAImagePullerTest.cpp index 37027ba1d..9cc618646 100644 --- a/tests/FPGAImagePullerTest.cpp +++ b/tests/FPGAImagePullerTest.cpp @@ -165,7 +165,7 @@ namespace { JFJochReceiverService service(devices, logger, pusher, 256); service.NumThreads(4); service.SetSpotFindingSettings(Spots()); - service.UseFPGAImagePuller(puller ? FPGAImagePullerUse::Always : FPGAImagePullerUse::Never); + service.FPGAImagePullerSettings(FPGAImagePuller::DefaultSlots, false, 0, puller); service.RugnuxLive(rugnux, nullptr, 2, 30); PixelMask mask(x); @@ -419,7 +419,7 @@ TEST_CASE("FPGAImagePuller_SameAsFPGA_EIGER_32bit", "[FPGAImagePuller]") { CollectingPusher pusher; JFJochReceiverService service(devices, logger, pusher, 256); service.NumThreads(4).SetSpotFindingSettings(Spots()); - service.UseFPGAImagePuller(puller ? FPGAImagePullerUse::Always : FPGAImagePullerUse::Never); + service.FPGAImagePullerSettings(FPGAImagePuller::DefaultSlots, false, 0, puller); PixelMask mask(x); service.Start(x, mask, nullptr); const auto out = service.Stop(); @@ -541,7 +541,7 @@ TEST_CASE("FPGAImagePuller_SlowConsumer_Receiver", "[FPGAImagePuller]") { pusher.delay = 3s; JFJochReceiverService service(devices, logger, pusher, 256); service.NumThreads(1).SetSpotFindingSettings(Spots()); - service.UseFPGAImagePuller(FPGAImagePullerUse::Always, 2); + service.FPGAImagePullerSettings(2, false, 0, true); PixelMask mask(x); const JFCalibration calib = Calibration(x); @@ -654,7 +654,7 @@ TEST_CASE("FPGAImagePuller_Cancel", "[FPGAImagePuller]") { CollectingPusher pusher; JFJochReceiverService service(devices, logger, pusher, 256); service.NumThreads(2).SetSpotFindingSettings(Spots()); - service.UseFPGAImagePuller(FPGAImagePullerUse::Always); + service.FPGAImagePullerSettings(FPGAImagePuller::DefaultSlots, false, 0, true); PixelMask mask(x); const JFCalibration calib = Calibration(x); service.Start(x, mask, &calib); @@ -689,7 +689,7 @@ TEST_CASE("FPGAImagePuller_NotForPedestalAndHostSummation", "[FPGAImagePuller]") CollectingPusher pusher; JFJochReceiverService service(devices, logger, pusher, 256); service.NumThreads(4).SetSpotFindingSettings(Spots()); - service.UseFPGAImagePuller(FPGAImagePullerUse::Always); + service.FPGAImagePullerSettings(FPGAImagePuller::DefaultSlots, false, 0, true); PixelMask mask(x); const JFCalibration calib = Calibration(x); service.Start(x, mask, &calib); @@ -860,7 +860,7 @@ TEST_CASE("FPGAImagePuller_Writer", "[FPGAImagePuller]") { HDF5FilePusher pusher; JFJochReceiverService service(devices, logger, pusher, 256); service.NumThreads(2).SetSpotFindingSettings(Spots()); - service.UseFPGAImagePuller(FPGAImagePullerUse::Always); + service.FPGAImagePullerSettings(FPGAImagePuller::DefaultSlots, false, 0, true); PixelMask mask(x); const JFCalibration calib = Calibration(x); service.Start(x, mask, &calib); diff --git a/tests/JFJochReceiverProcessingTest.cpp b/tests/JFJochReceiverProcessingTest.cpp index 9012745f0..312a92dd5 100644 --- a/tests/JFJochReceiverProcessingTest.cpp +++ b/tests/JFJochReceiverProcessingTest.cpp @@ -157,8 +157,6 @@ TEST_CASE("JFJochIntegrationTest_ZMQ_crystal_spot_and_index_GPUStills", "[JFJoch service.Indexing(experiment.GetIndexingSettings()); // Serial data with rugnux on: the converted frames are analysed on the GPU, after the pre-pass. service.RugnuxLive(true, nullptr, 4, 60); - // The default (FPGAImagePuller and JFJochReceiverRugnuxStills) and JFJochReceiverFPGA's own live stills - service.UseFPGAImagePuller(GENERATE(FPGAImagePullerUse::RugnuxLive, FPGAImagePullerUse::Never)); // No progress value at the start of measurement REQUIRE(!service.GetProgress().has_value()); @@ -236,8 +234,6 @@ TEST_CASE("JFJochIntegrationTest_ZMQ_GPUStills_writer_down", "[JFJochReceiver]") service.NumThreads(4); service.Indexing(experiment.GetIndexingSettings()); service.RugnuxLive(true, nullptr, 4, 60); - // The default (FPGAImagePuller and JFJochReceiverRugnuxStills) and JFJochReceiverFPGA's own live stills - service.UseFPGAImagePuller(GENERATE(FPGAImagePullerUse::RugnuxLive, FPGAImagePullerUse::Never)); service.Start(experiment, pixel_mask, nullptr); REQUIRE_THROWS_AS(service.Stop(), JFJochException); @@ -279,8 +275,6 @@ TEST_CASE("JFJochIntegrationTest_GPUStills_cancel_during_prepass", "[JFJochRecei service.NumThreads(4); service.Indexing(experiment.GetIndexingSettings()); service.RugnuxLive(true, nullptr, 4, 60); - // The default (FPGAImagePuller and JFJochReceiverRugnuxStills) and JFJochReceiverFPGA's own live stills - service.UseFPGAImagePuller(GENERATE(FPGAImagePullerUse::RugnuxLive, FPGAImagePullerUse::Never)); service.Start(experiment, pixel_mask, nullptr); std::this_thread::sleep_for(std::chrono::seconds(3)); diff --git a/tests/StillsGPUAnalysisFPGATest.cpp b/tests/StillsGPUAnalysisFPGATest.cpp deleted file mode 100644 index a2129bf4e..000000000 --- a/tests/StillsGPUAnalysisFPGATest.cpp +++ /dev/null @@ -1,127 +0,0 @@ -// SPDX-FileCopyrightText: 2026 Filip Leonarski, Paul Scherrer Institute -// SPDX-License-Identifier: GPL-3.0-only - -#include - -#include - -#include "../common/ImageBuffer.h" -#include "../receiver/StillsGPUAnalysisFPGA.h" - -namespace { - DiffractionExperiment StillsExperiment() { - DiffractionExperiment x(DetJF(1)); - x.ImagesPerTrigger(StillsGPUAnalysisFPGA::PREPASS_IMAGES + 200).NumTriggers(1).DetectorDistance_mm(100).BeamX_pxl(500).BeamY_pxl(250) - .IncidentEnergy_keV(12.4); - return x; - } - - // A frame after the pre-pass's sample (numbers from PREPASS_IMAGES on are never in it), in a slot of `buffer`. - std::shared_ptr Frame(ImageBuffer &buffer, int64_t number) { - auto held = std::make_shared(); - held->slot = buffer.GetImageSlot(); - REQUIRE(held->slot != nullptr); - held->message.number = StillsGPUAnalysisFPGA::PREPASS_IMAGES + number; - held->message.image_collection_efficiency = 1.0f; - return held; - } - - StartMessage Start(const DiffractionExperiment &x) { - StartMessage start; - x.FillMessage(start); - return start; - } -} - -TEST_CASE("StillsGPUAnalysisFPGA_StartFailureReleasesThreads", "[StillsGPUAnalysisFPGA]") { - Logger logger(Catch::getResultCapture().getCurrentTestName()); - const DiffractionExperiment x = StillsExperiment(); - const PixelMask mask(x); - ImageBuffer buffer(64 * 1024 * 1024); - buffer.StartMeasurement(x); - RugnuxLiveStatus status; - - std::atomic failed = 0, sunk = 0; - { - StillsGPUAnalysisFPGA gpu(x, mask, Start(x), nullptr, 4, 100, logger, - [](const StillsGPUAnalysisFPGA::Setup &) { - throw JFJochException(JFJochExceptionCategory::ZeroMQ, "Timeout on pushing start message"); - }, - [&](DataMessage &, const AzimuthalIntegrationProfile &) { ++sunk; }, - [] { return DiffractionExperiment::DefaultDataProcessingSettings(); }, - [&](const JFJochException &) { ++failed; }, &status); - for (int i = 0; i < 3; i++) - REQUIRE(gpu.Hold(Frame(buffer, i))); - REQUIRE_THROWS_AS(gpu.Finish(), JFJochException); - } - CHECK(failed == 1); - CHECK(sunk == 0); - CHECK(status.Get().state == RugnuxLiveState::Failed); - // Every slot the frames were held in is back. - CHECK(buffer.GetAvailSlots() == buffer.GetStatus().total_slots); -} - -TEST_CASE("StillsGPUAnalysisFPGA_HoldIsBounded", "[StillsGPUAnalysisFPGA]") { - Logger logger(Catch::getResultCapture().getCurrentTestName()); - const DiffractionExperiment x = StillsExperiment(); - const PixelMask mask(x); - ImageBuffer buffer(64 * 1024 * 1024); - buffer.StartMeasurement(x); - REQUIRE(buffer.GetStatus().total_slots >= 4); - - StillsGPUAnalysisFPGA gpu(x, mask, Start(x), nullptr, 2, 3, logger, - [](const StillsGPUAnalysisFPGA::Setup &) { - throw JFJochException(JFJochExceptionCategory::ZeroMQ, "no writer"); - }, - [](DataMessage &, const AzimuthalIntegrationProfile &) {}, - [] { return DiffractionExperiment::DefaultDataProcessingSettings(); }); - // The analysis waits for the pre-pass, which waits for its sample: nothing is taken off the queue. - for (int i = 0; i < 3; i++) - REQUIRE(gpu.Hold(Frame(buffer, i))); - { - const auto refused = Frame(buffer, 3); - CHECK(!gpu.Hold(refused)); - } - CHECK(buffer.GetStatus().preparation_slots == 3); - REQUIRE_THROWS(gpu.Finish()); - CHECK(buffer.GetStatus().preparation_slots == 0); -} - -TEST_CASE("StillsGPUAnalysisFPGA_FailingFrameDoesNotStopAnalysis", "[StillsGPUAnalysisFPGA]") { - Logger logger(Catch::getResultCapture().getCurrentTestName()); - const DiffractionExperiment x = StillsExperiment(); - const PixelMask mask(x); - ImageBuffer buffer(64 * 1024 * 1024); - buffer.StartMeasurement(x); - RugnuxLiveStatus status; - - std::atomic sunk = 0; - StillsGPUAnalysisFPGA gpu(x, mask, Start(x), nullptr, 1, 100, logger, - [](const StillsGPUAnalysisFPGA::Setup &) {}, - [&](DataMessage &m, const AzimuthalIntegrationProfile &) { - ++sunk; - if (m.number == StillsGPUAnalysisFPGA::PREPASS_IMAGES) - throw std::runtime_error("not a JFJochException"); - }, - [] { return DiffractionExperiment::DefaultDataProcessingSettings(); }, - {}, &status); - // The frames carry no image, so their analysis fails too - they are passed on all the same. - for (int i = 0; i < 3; i++) - REQUIRE(gpu.Hold(Frame(buffer, i))); - REQUIRE_NOTHROW(gpu.Finish()); - CHECK(sunk == 3); - // The outcome waits for everything to be written, and comes after the latency. - CHECK(status.Get().state == RugnuxLiveState::Running); - CHECK(!status.Get().last_image_to_written_s); - gpu.Written(); - const auto s = status.Get(); - CHECK(s.state == RugnuxLiveState::Failed); - CHECK(!s.message.empty()); - REQUIRE(s.last_image_to_written_s); - REQUIRE(s.last_image_s); - CHECK(s.elapsed_s >= s.last_image_s.value() + s.last_image_to_written_s.value() - 1e-6); - REQUIRE(!s.steps.empty()); - CHECK(s.steps.back().title == "Writing"); - CHECK(s.steps.back().duration_s); - CHECK(buffer.GetStatus().preparation_slots == 0); -} diff --git a/tools/jfjoch_fpga_stills_test.cpp b/tools/jfjoch_fpga_stills_test.cpp index 09e0eacd6..040b1f375 100644 --- a/tools/jfjoch_fpga_stills_test.cpp +++ b/tools/jfjoch_fpga_stills_test.cpp @@ -41,8 +41,6 @@ void print_usage(Logger &logger) { logger.Info(" -r Rates the source is paced at, one collection each (default: 0 = as fast as it goes)"); logger.Info(" -p FPGAImagePuller slots (default 128)"); logger.Info(" -d Not blocking, as the broker runs: images the host has no room for are dropped"); - logger.Info(" -F JFJochReceiverFPGA's own live stills instead of FPGAImagePuller (not blocking: frames"); - logger.Info(" past what its analysis holds are lost)"); logger.Info(" -K{} Mock of the card instead of /dev/jfjoch* (optional: its generator memory, default 64 MiB ="); logger.Info(" 128 module frames)"); } @@ -88,7 +86,7 @@ int64_t GeneratorImages(AcquisitionDeviceGroup &aq_devices, const DiffractionExp bool RunDataset(Logger &logger, AcquisitionDeviceGroup &aq_devices, const std::string &file, std::optional nimages, uint16_t nstreams, uint16_t nthreads, size_t send_buffer_size_MiB, const IndexingSettings &indexing, const std::optional &cell, size_t puller_slots, - bool fpga_receiver, const std::vector &rates, bool dropping) { + const std::vector &rates, bool dropping) { RegisterHDF5Filter(); JFJochHDF5Reader reader; reader.ReadFile(file); @@ -166,13 +164,10 @@ bool RunDataset(Logger &logger, AcquisitionDeviceGroup &aq_devices, const std::s for (const double rate: rates) { // Blocking at source: the puller waits for a free slot and the receiver for room in the image buffer, - // the cards hold their frames and their generators stall. JFJochReceiverFPGA's live stills cannot block. - service.UseFPGAImagePuller(fpga_receiver ? FPGAImagePullerUse::Never : FPGAImagePullerUse::RugnuxLive, - puller_slots, !dropping, rate); + // the cards hold their frames and their generators stall + service.FPGAImagePullerSettings(puller_slots, !dropping, rate); logger.Info(""); - logger.Info("=== {}, {} ===", fpga_receiver ? "JFJochReceiverFPGA (not blocking)" - : fmt::format("FPGAImagePuller ({} slots, {})", puller_slots, - dropping ? "dropping" : "blocking"), + logger.Info("=== FPGAImagePuller ({} slots, {}), {} ===", puller_slots, dropping ? "dropping" : "blocking", (rate > 0) ? fmt::format("source paced at {:.1f} Hz", rate) : std::string("source as fast as it goes")); rusage usage_start{}; @@ -289,14 +284,13 @@ int main(int argc, char **argv) { IndexingAlgorithmEnum indexing = IndexingAlgorithmEnum::Auto; uint16_t indexing_threads = 4; size_t puller_slots = FPGAImagePuller::DefaultSlots; - bool fpga_receiver = false; std::optional mock_card_MiB; bool verbose = false; std::vector rates = {0}; bool dropping = false; int opt; - while ((opt = getopt(argc, argv, "vi:s:N:B:C:X:t:r:p:dFK::")) != -1) { + while ((opt = getopt(argc, argv, "vi:s:N:B:C:X:t:r:p:dK::")) != -1) { switch (opt) { case 'v': verbose = true; @@ -346,9 +340,6 @@ int main(int argc, char **argv) { case 'p': puller_slots = atol(optarg); break; - case 'F': - fpga_receiver = true; - break; case 'd': dropping = true; break; @@ -387,7 +378,7 @@ int main(int argc, char **argv) { bool ret = false; try { ret = RunDataset(logger, aq_devices, argv[optind], nimages, nstreams, nthreads, send_buffer_size_MiB, - i_settings, cell, puller_slots, fpga_receiver, rates, dropping); + i_settings, cell, puller_slots, rates, dropping); } catch (std::exception &e) { logger.Error(e.what()); } From c52125bf4356d2d9376678cf2741f170bc0115ea Mon Sep 17 00:00:00 2001 From: Filip Leonarski Date: Wed, 18 Nov 2026 12:31:39 +0100 Subject: [PATCH 16/41] Rugnux live: stills_downsample, 1 of every F serial images analysed, chosen by a hash A serial collection can be analysed on a fraction of its images, to keep up with a stream faster than the analysis. Not a stride, which is in step with periodic patterns of the stream (pump-probe on/off, storage cells, module or card interleave) and could take only the dark frames: each image is chosen on its own with probability 1/F from the SplitMix64 finaliser of its number, salted (StillsImageSelected), reproducible and the same on every thread and card. The first StillsGPUAnalysis::PREPASS_MAX_IMAGES (2000) images are all taken, as the pre-pass may use any of them. An image not chosen is counted as collected and skipped before the analysis, neither analysed nor written - as one the serial filter leaves out. - OpenAPI rugnux_settings / rugnux_status: stills_downsample (int64, >= 1, default 1); C++ model and frontend client regenerated; the Rugnux settings page gets the field. Kept by POST /initialize, as reserved_cpus. - JFJochReceiverService::RugnuxLive, JFJochStateMachine::SetRugnuxLive, JFJochReceiverRugnuxStills take it. - jfjoch_fpga_stills_test -k , jfjoch_stills_gpu_replay -k . - StillsSelectionTest: fraction within 5 sigma for F = 2, 3, 4, 10 over 400k images, every phase of a period-2 and a period-F pattern gets its share, deterministic, pre-pass images and F = 1 all taken. Measured (mock, 9M, 6000 images, -k 4): 2984 analysed = 0.497 (expected 0.5 with the first 2000 all in; 0.246 of the rest). Host-only replay of 10000 serial 8M images: 17.0 s -> 10.0 s in all, after the pre-pass 10.6 s -> 3.4 s. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01UqXYdHHZ4cogS1mrGUtfN7 --- broker/JFJochBrokerHttp.cpp | 3 +- broker/JFJochBrokerParser.cpp | 3 +- broker/JFJochServices.cpp | 2 +- broker/JFJochServices.h | 1 + broker/JFJochStateMachine.cpp | 3 +- broker/JFJochStateMachine.h | 3 +- broker/gen/model/Rugnux_settings.cpp | 47 +++++++++++++++++++++- broker/gen/model/Rugnux_settings.h | 9 +++++ broker/gen/model/Rugnux_status.cpp | 31 +++++++++++++- broker/gen/model/Rugnux_status.h | 9 +++++ broker/jfjoch_api.yaml | 15 +++++++ docs/ACKNOWLEDGEMENT.md | 3 +- docs/JFJOCH_BROKER.md | 28 ++++++++----- docs/TOOLS.md | 5 ++- frontend/src/client/types.gen.ts | 13 ++++++ frontend/src/client/zod.gen.ts | 4 +- frontend/src/components/RugnuxSettings.tsx | 15 +++++-- receiver/JFJochReceiverRugnuxStills.cpp | 10 ++++- receiver/JFJochReceiverRugnuxStills.h | 4 +- receiver/JFJochReceiverService.cpp | 5 ++- receiver/JFJochReceiverService.h | 4 +- receiver/StillsSelection.h | 22 ++++++++++ tests/CMakeLists.txt | 1 + tests/StillsSelectionTest.cpp | 42 +++++++++++++++++++ tools/jfjoch_fpga_stills_test.cpp | 16 +++++--- tools/jfjoch_stills_gpu_replay.cpp | 8 +++- 26 files changed, 268 insertions(+), 38 deletions(-) create mode 100644 receiver/StillsSelection.h create mode 100644 tests/StillsSelectionTest.cpp diff --git a/broker/JFJochBrokerHttp.cpp b/broker/JFJochBrokerHttp.cpp index bbbba1e94..c1f542592 100644 --- a/broker/JFJochBrokerHttp.cpp +++ b/broker/JFJochBrokerHttp.cpp @@ -1018,6 +1018,7 @@ void JFJochBrokerHttp::config_rugnux_get(httplib::Response &response) { ret.setDeadlineS(s.deadline_s); ret.setRefineSolvent(s.refine_solvent); ret.setForceStill(s.force_still); + ret.setStillsDownsample(s.stills_downsample); ret.setModelLoaded(s.model != nullptr); if (s.model) ret.setModelSizeBytes(s.model_size_bytes); @@ -1028,7 +1029,7 @@ void JFJochBrokerHttp::config_rugnux_put(const Rugnux_settings &rugnuxSettings, httplib::Response &response) { state_machine.SetRugnuxLive(rugnuxSettings.isEnable(), rugnuxSettings.getReservedCpus(), rugnuxSettings.getDeadlineS(), rugnuxSettings.isRefineSolvent(), - rugnuxSettings.isForceStill()); + rugnuxSettings.isForceStill(), rugnuxSettings.getStillsDownsample()); response.status = 200; } diff --git a/broker/JFJochBrokerParser.cpp b/broker/JFJochBrokerParser.cpp index d03ba5387..fab1147f5 100644 --- a/broker/JFJochBrokerParser.cpp +++ b/broker/JFJochBrokerParser.cpp @@ -283,7 +283,8 @@ void ParseRugnuxSettings(const org::openapitools::server::model::Jfjoch_settings .reserved_cpus = input.getRugnux().getReservedCpus(), .deadline_s = input.getRugnux().getDeadlineS(), .refine_solvent = input.getRugnux().isRefineSolvent(), - .force_still = input.getRugnux().isForceStill() + .force_still = input.getRugnux().isForceStill(), + .stills_downsample = input.getRugnux().getStillsDownsample() }); } diff --git a/broker/JFJochServices.cpp b/broker/JFJochServices.cpp index f992be1de..bae2e856e 100644 --- a/broker/JFJochServices.cpp +++ b/broker/JFJochServices.cpp @@ -385,7 +385,7 @@ void JFJochServices::SetupIndexing(const IndexingSettings &input) { void JFJochServices::SetRugnuxLive(const RugnuxLiveSettings &input) { if (receiver) receiver->RugnuxLive(input.enable, input.model, input.reserved_cpus, input.deadline_s, input.refine_solvent, - input.force_still); + input.force_still, input.stills_downsample); rugnux = input; } diff --git a/broker/JFJochServices.h b/broker/JFJochServices.h index 22d2e777e..b1c1a7c6f 100644 --- a/broker/JFJochServices.h +++ b/broker/JFJochServices.h @@ -20,6 +20,7 @@ struct RugnuxLiveSettings { double deadline_s = 60; // the analysis is cut this long after the last image (0 = never) bool refine_solvent = false; // the refinement of a placed model builds the solvent (rugnux --refine-solvent) bool force_still = false; // rotation collections are processed as stills (rugnux --force-still) + int64_t stills_downsample = 1; // serial collections: 1 of every this many images analysed on average std::shared_ptr model; // null = no model int64_t model_size_bytes = 0; // as uploaded }; diff --git a/broker/JFJochStateMachine.cpp b/broker/JFJochStateMachine.cpp index 1097063ea..67c72d22e 100644 --- a/broker/JFJochStateMachine.cpp +++ b/broker/JFJochStateMachine.cpp @@ -1226,7 +1226,7 @@ IndexingSettings JFJochStateMachine::GetIndexingSettings() const { } void JFJochStateMachine::SetRugnuxLive(bool enable, int64_t reserved_cpus, double deadline_s, bool refine_solvent, - bool force_still) { + bool force_still, int64_t stills_downsample) { std::unique_lock ul(m); if (IsRunning()) throw WrongDAQStateException("Cannot change rugnux settings during data collection"); @@ -1237,6 +1237,7 @@ void JFJochStateMachine::SetRugnuxLive(bool enable, int64_t reserved_cpus, doubl s.deadline_s = deadline_s; s.refine_solvent = refine_solvent; s.force_still = force_still; + s.stills_downsample = stills_downsample; services.SetRugnuxLive(s); } diff --git a/broker/JFJochStateMachine.h b/broker/JFJochStateMachine.h index 10ac694ee..d6f9ee9a1 100644 --- a/broker/JFJochStateMachine.h +++ b/broker/JFJochStateMachine.h @@ -248,7 +248,8 @@ public: void SetIndexingSettings(const IndexingSettings &input); IndexingSettings GetIndexingSettings() const; - void SetRugnuxLive(bool enable, int64_t reserved_cpus, double deadline_s, bool refine_solvent, bool force_still); + void SetRugnuxLive(bool enable, int64_t reserved_cpus, double deadline_s, bool refine_solvent, bool force_still, + int64_t stills_downsample = 1); void SetRugnuxModel(std::shared_ptr model, int64_t size_bytes); // null = remove the model RugnuxLiveSettings GetRugnuxLive() const; RugnuxLiveSnapshot GetRugnuxStatus() const; diff --git a/broker/gen/model/Rugnux_settings.cpp b/broker/gen/model/Rugnux_settings.cpp index b5831f9ae..a2d4a6db1 100644 --- a/broker/gen/model/Rugnux_settings.cpp +++ b/broker/gen/model/Rugnux_settings.cpp @@ -31,6 +31,8 @@ Rugnux_settings::Rugnux_settings() m_Refine_solventIsSet = false; m_Force_still = false; m_Force_stillIsSet = false; + m_Stills_downsample = 1L; + m_Stills_downsampleIsSet = false; } @@ -81,7 +83,21 @@ bool Rugnux_settings::validate(std::stringstream& msg, const std::string& pathPr } } - + + if (stillsDownsampleIsSet()) + { + const int64_t& value = m_Stills_downsample; + const std::string currentValuePath = _pathPrefix + ".stillsDownsample"; + + + if (value < 1ll) + { + success = false; + msg << currentValuePath << ": must be greater than or equal to 1;"; + } + + } + return success; } @@ -103,7 +119,10 @@ bool Rugnux_settings::operator==(const Rugnux_settings& rhs) const ((!refineSolventIsSet() && !rhs.refineSolventIsSet()) || (refineSolventIsSet() && rhs.refineSolventIsSet() && isRefineSolvent() == rhs.isRefineSolvent())) && - ((!forceStillIsSet() && !rhs.forceStillIsSet()) || (forceStillIsSet() && rhs.forceStillIsSet() && isForceStill() == rhs.isForceStill())) + ((!forceStillIsSet() && !rhs.forceStillIsSet()) || (forceStillIsSet() && rhs.forceStillIsSet() && isForceStill() == rhs.isForceStill())) && + + + ((!stillsDownsampleIsSet() && !rhs.stillsDownsampleIsSet()) || (stillsDownsampleIsSet() && rhs.stillsDownsampleIsSet() && getStillsDownsample() == rhs.getStillsDownsample())) ; } @@ -126,6 +145,8 @@ void to_json(nlohmann::json& j, const Rugnux_settings& o) j["refine_solvent"] = o.m_Refine_solvent; if(o.forceStillIsSet()) j["force_still"] = o.m_Force_still; + if(o.stillsDownsampleIsSet()) + j["stills_downsample"] = o.m_Stills_downsample; } @@ -156,6 +177,11 @@ void from_json(const nlohmann::json& j, Rugnux_settings& o) j.at("force_still").get_to(o.m_Force_still); o.m_Force_stillIsSet = true; } + if(j.find("stills_downsample") != j.end()) + { + j.at("stills_downsample").get_to(o.m_Stills_downsample); + o.m_Stills_downsampleIsSet = true; + } } @@ -244,6 +270,23 @@ void Rugnux_settings::unsetForce_still() { m_Force_stillIsSet = false; } +int64_t Rugnux_settings::getStillsDownsample() const +{ + return m_Stills_downsample; +} +void Rugnux_settings::setStillsDownsample(int64_t const value) +{ + m_Stills_downsample = value; + m_Stills_downsampleIsSet = true; +} +bool Rugnux_settings::stillsDownsampleIsSet() const +{ + return m_Stills_downsampleIsSet; +} +void Rugnux_settings::unsetStills_downsample() +{ + m_Stills_downsampleIsSet = false; +} } // namespace org::openapitools::server::model diff --git a/broker/gen/model/Rugnux_settings.h b/broker/gen/model/Rugnux_settings.h index 066b9d719..4e2ad0b49 100644 --- a/broker/gen/model/Rugnux_settings.h +++ b/broker/gen/model/Rugnux_settings.h @@ -92,6 +92,13 @@ public: void setForceStill(bool const value); bool forceStillIsSet() const; void unsetForce_still(); + /// + /// Serial collections: analyse on average 1 of every this many images, to keep up with a fast stream. Each image is chosen on its own with probability 1 / stills_downsample from a hash of its number - not a stride, which would be in step with periodic patterns (pump-probe on/off, storage cells). The images the pre-pass may use (the first 2000) are all analysed. Images not chosen are counted, not analysed and not written. 1: every image. + /// + int64_t getStillsDownsample() const; + void setStillsDownsample(int64_t const value); + bool stillsDownsampleIsSet() const; + void unsetStills_downsample(); friend void to_json(nlohmann::json& j, const Rugnux_settings& o); friend void from_json(const nlohmann::json& j, Rugnux_settings& o); @@ -106,6 +113,8 @@ protected: bool m_Refine_solventIsSet; bool m_Force_still; bool m_Force_stillIsSet; + int64_t m_Stills_downsample; + bool m_Stills_downsampleIsSet; }; diff --git a/broker/gen/model/Rugnux_status.cpp b/broker/gen/model/Rugnux_status.cpp index f265d124e..d085edc75 100644 --- a/broker/gen/model/Rugnux_status.cpp +++ b/broker/gen/model/Rugnux_status.cpp @@ -27,6 +27,8 @@ Rugnux_status::Rugnux_status() m_Deadline_sIsSet = false; m_Refine_solvent = false; m_Force_still = false; + m_Stills_downsample = 0L; + m_Stills_downsampleIsSet = false; m_Model_loaded = false; m_Model_size_bytes = 0L; m_Model_size_bytesIsSet = false; @@ -52,7 +54,7 @@ bool Rugnux_status::validate(std::stringstream& msg, const std::string& pathPref bool success = true; const std::string _pathPrefix = pathPrefix.empty() ? "Rugnux_status" : pathPrefix; - + return success; } @@ -76,6 +78,9 @@ bool Rugnux_status::operator==(const Rugnux_status& rhs) const (isForceStill() == rhs.isForceStill()) && + + ((!stillsDownsampleIsSet() && !rhs.stillsDownsampleIsSet()) || (stillsDownsampleIsSet() && rhs.stillsDownsampleIsSet() && getStillsDownsample() == rhs.getStillsDownsample())) && + (isModelLoaded() == rhs.isModelLoaded()) && @@ -99,6 +104,8 @@ void to_json(nlohmann::json& j, const Rugnux_status& o) j["deadline_s"] = o.m_Deadline_s; j["refine_solvent"] = o.m_Refine_solvent; j["force_still"] = o.m_Force_still; + if(o.stillsDownsampleIsSet()) + j["stills_downsample"] = o.m_Stills_downsample; j["model_loaded"] = o.m_Model_loaded; if(o.modelSizeBytesIsSet()) j["model_size_bytes"] = o.m_Model_size_bytes; @@ -116,6 +123,11 @@ void from_json(const nlohmann::json& j, Rugnux_status& o) } j.at("refine_solvent").get_to(o.m_Refine_solvent); j.at("force_still").get_to(o.m_Force_still); + if(j.find("stills_downsample") != j.end()) + { + j.at("stills_downsample").get_to(o.m_Stills_downsample); + o.m_Stills_downsampleIsSet = true; + } j.at("model_loaded").get_to(o.m_Model_loaded); if(j.find("model_size_bytes") != j.end()) { @@ -174,6 +186,23 @@ void Rugnux_status::setForceStill(bool const value) { m_Force_still = value; } +int64_t Rugnux_status::getStillsDownsample() const +{ + return m_Stills_downsample; +} +void Rugnux_status::setStillsDownsample(int64_t const value) +{ + m_Stills_downsample = value; + m_Stills_downsampleIsSet = true; +} +bool Rugnux_status::stillsDownsampleIsSet() const +{ + return m_Stills_downsampleIsSet; +} +void Rugnux_status::unsetStills_downsample() +{ + m_Stills_downsampleIsSet = false; +} bool Rugnux_status::isModelLoaded() const { return m_Model_loaded; diff --git a/broker/gen/model/Rugnux_status.h b/broker/gen/model/Rugnux_status.h index 6a8565b84..8ca615541 100644 --- a/broker/gen/model/Rugnux_status.h +++ b/broker/gen/model/Rugnux_status.h @@ -85,6 +85,13 @@ public: bool isForceStill() const; void setForceStill(bool const value); /// + /// Serial collections, 1 of every this many images analysed on average + /// + int64_t getStillsDownsample() const; + void setStillsDownsample(int64_t const value); + bool stillsDownsampleIsSet() const; + void unsetStills_downsample(); + /// /// A model was uploaded with `PUT /config/rugnux/model` /// bool isModelLoaded() const; @@ -110,6 +117,8 @@ protected: bool m_Force_still; + int64_t m_Stills_downsample; + bool m_Stills_downsampleIsSet; bool m_Model_loaded; int64_t m_Model_size_bytes; diff --git a/broker/jfjoch_api.yaml b/broker/jfjoch_api.yaml index 28a9f42c1..eae6e7825 100644 --- a/broker/jfjoch_api.yaml +++ b/broker/jfjoch_api.yaml @@ -2841,6 +2841,17 @@ components: description: | Process DECTRIS rotation collections as stills, on the serial path (pre-pass, GPU analysis, stills merge), as `rugnux --force-still` does. The written file keeps its goniometer. Reset to false by `POST /initialize`. + stills_downsample: + type: integer + format: int64 + minimum: 1 + default: 1 + description: | + Serial collections: analyse on average 1 of every this many images, to keep up with a fast stream. Each + image is chosen on its own with probability 1 / stills_downsample from a hash of its number - not a stride, + which would be in step with periodic patterns (pump-probe on/off, storage cells). The images the pre-pass + may use (the first 2000) are all analysed. Images not chosen are counted, not analysed and not written. + 1: every image. rugnux_status: type: object required: @@ -2867,6 +2878,10 @@ components: force_still: type: boolean description: DECTRIS rotation collections are processed as stills + stills_downsample: + type: integer + format: int64 + description: Serial collections, 1 of every this many images analysed on average model_loaded: type: boolean description: A model was uploaded with `PUT /config/rugnux/model` diff --git a/docs/ACKNOWLEDGEMENT.md b/docs/ACKNOWLEDGEMENT.md index aa2328e36..6dae81cae 100644 --- a/docs/ACKNOWLEDGEMENT.md +++ b/docs/ACKNOWLEDGEMENT.md @@ -841,7 +841,8 @@ jackknife" (1979), Ann. Statist. 7, 1-26 [doi:10.1214/aos/1176344552](https://doi.org/10.1214/aos/1176344552). Its draws are Poisson weights hashed with the SplitMix64 finaliser of G. L. Steele Jr., D. Lea and C. H. Flood, "Fast splittable pseudorandom number generators" (2014), Proc. OOPSLA 2014, 453-472 -[doi:10.1145/2660193.2660195](https://doi.org/10.1145/2660193.2660195). +[doi:10.1145/2660193.2660195](https://doi.org/10.1145/2660193.2660195). The same finaliser chooses the images rugnux live +stills analyses with `stills_downsample`. **Error-free floating-point arithmetic** — the single-precision exp shared between the CPU and an Apple GPU (`BraggExp.h`) and the double-float sums of the refinement's Gauss-Newton products on the GPU diff --git a/docs/JFJOCH_BROKER.md b/docs/JFJOCH_BROKER.md index 4ff231d9a..9cef7084f 100644 --- a/docs/JFJOCH_BROKER.md +++ b/docs/JFJOCH_BROKER.md @@ -204,8 +204,7 @@ back to the broker, so with it the route answers 409. ## Online analysis -Without rugnux live mode, and in the FPGA workflow also for a rotation collection with it, the broker analyses each -image on its own: masking, summation, azimuthal and ROI integration, spot finding, and - with indexing on - indexing +Without rugnux live mode the broker analyses each image on its own: masking, summation, azimuthal and ROI integration, spot finding, and - with indexing on - indexing of the image and refinement of its geometry (`geom_refinement_algorithm`). A rotation collection is indexed image by image, as a serial one. The broker neither integrates Bragg reflections nor determines a lattice for the whole rotation sweep, so the reflections, the per-image B-factor and integrated-reflection count, and the rotation lattice are filled only where @@ -221,7 +220,9 @@ goniometer and the rugnux live setting: | Input | Run | Receiver | What it does | |---|---|---|---| -| FPGA cards (PSI JUNGFRAU, PSI EIGER) | every run | `JFJochReceiverFPGA` | the card's converted pixels, spots, azimuthal and ROI sums into the image; summation on the host above what the card sums; indexing of each image; the calibration to the writer; pedestal runs into the pedestal and its RMS; with rugnux live on, a serial run analysed on the GPU after a rugnux pre-pass (see [Serial collections](#serial-collections-experimental)) | +| FPGA cards (PSI JUNGFRAU, PSI EIGER) | pedestal run | `JFJochReceiverPedestal` | the raw frames into the pedestal and its RMS; nothing on any stream | +| FPGA cards | rugnux live off, or summation on the host | `JFJochReceiverFPGA` | the card's converted pixels, spots, azimuthal and ROI sums into the image; summation on the host above what the card sums; indexing of each image; the calibration to the writer | +| FPGA cards | rugnux live on | `FPGAImagePuller`, then `JFJochReceiverRugnuxRotation` or `JFJochReceiverRugnuxStills` | the cards' frames assembled and compressed on the host into a stream as a DECTRIS detector gives, then taken as the DECTRIS rows below | | DECTRIS stream | dark-mask sequence | `JFJochReceiverDarkMask` | the dark frames into the mask; nothing on any stream | | DECTRIS stream | rugnux live off, or a rotation run the image buffer cannot hold | `JFJochReceiverLite` | each image on the GPU: masking, azimuthal and ROI integration, spot finding, indexing | | DECTRIS stream | rugnux live on, rotation that fits the image buffer | `JFJochReceiverRugnuxRotation` | images forwarded as they come; rugnux reads the collection back from the image buffer and runs the whole pipeline | @@ -240,8 +241,8 @@ more bins than the card holds needs. With rugnux live mode on, collections from a DECTRIS detector are processed inside the broker while they arrive: rotation collections by rugnux, and serial (stills) collections on the GPU with the geometry and mask a rugnux pre-pass decided (see [Serial collections](#serial-collections-experimental) below). In the FPGA workflow -(PSI JUNGFRAU and EIGER) serial collections are analysed on the GPU after a pre-pass as well, with the differences -given there; rotation collections run image by image, as with the mode off. It is off by default; the +(PSI JUNGFRAU and EIGER) the frames reach the same receivers through `FPGAImagePuller`, rotation and serial alike; +with summation on the host the collection runs image by image, as with the mode off. It is off by default; the configuration file switches it on with `"rugnux": {"enable": true, "reserved_cpus": 4}`, where `reserved_cpus` is the number of CPU threads left to the receiver and the image pusher. @@ -278,7 +279,14 @@ a placed model build the solvent as well: waters added at difference-map peaks a hold them, waters and ions relabelled; `model.refinement` in `/rugnux/status` then carries `waters_added` and `waters_removed`. `force_still` (`rugnux --force-still`) sends a rotation collection from a DECTRIS detector the serial way: pre-pass, GPU analysis and stills merge (see [Serial collections](#serial-collections-experimental)). -The analysis takes the frames without the goniometer; the master file keeps it. It does not change the FPGA workflow. +The analysis takes the frames without the goniometer; the master file keeps it. + +`stills_downsample` (default 1) lets a serial collection analyse on average 1 of every this many images, to keep up +with a stream faster than the analysis. Each image is chosen on its own, with probability 1 / `stills_downsample` +from a hash of its number: not every n-th image, which would be in step with a periodic pattern of the stream +(pump-probe on/off, storage cells) and could take, for example, only the dark frames. The choice is reproducible. +The first 2000 images, which the pre-pass may use, are all analysed. An image not chosen is counted as collected, +neither analysed nor written - as an image the serial filter leaves out. The end message, and with it the end of the collection, waits for the analysis. `deadline_s` (default 60 s; 0 for no cutoff) bounds that wait: this long after the last image the analysis is cut. `POST /cancel` is @@ -418,11 +426,9 @@ pre-pass state and duration, the stated and decided beam centre and distance, th images analysed and indexed with the analysis rate. The "Rugnux live" page of the web frontend shows the same. `tools/jfjoch_stills_gpu_replay` replays a stored serial collection through the same analysis. -In the FPGA workflow (JUNGFRAU), a serial collection with rugnux live mode on is analysed by the receiver of the -card (`JFJochReceiverFPGA`) with the pre-pass, the GPU analysis and the live merge described above, with three -differences: the converted frames wait for the analysis in at most half of the image buffer's slots, a frame that -finds them taken is dropped, and there is no model step - an uploaded model is not placed or refined on these -merges. The end message carries the merged data, as for a DECTRIS stream. +In the FPGA workflow (JUNGFRAU), a serial collection with rugnux live mode on is assembled on the host by +`FPGAImagePuller` and analysed by `JFJochReceiverRugnuxStills` exactly as a DECTRIS stream. +`tools/jfjoch_fpga_stills_test` measures this path on the cards with a stored dataset (see [Tools](TOOLS.md)). ## Setting up a local test for Jungfraujoch For development, it is possible to set up a local installation of Jungfraujoch. diff --git a/docs/TOOLS.md b/docs/TOOLS.md index 30da17140..c410dd341 100644 --- a/docs/TOOLS.md +++ b/docs/TOOLS.md @@ -74,7 +74,7 @@ synthesis C model on the CPU, so no FPGA device is required. Measures rugnux live stills on the FPGA card(s), with a stored dataset standing in for the detector: ``` -jfjoch_fpga_stills_test [-i ] [-s ] [-N ] [-B ] [-C a,b,c,al,be,ga] [-X ] [-r ,...] [-p ] [-d] [-v] [-K[]] +jfjoch_fpga_stills_test [-i ] [-s ] [-N ] [-B ] [-C a,b,c,al,be,ga] [-X ] [-r ,...] [-p ] [-k ] [-d] [-v] [-K[]] ``` - The dataset must be a stored JUNGFRAU dataset with its modules assembled (1030 x 514 each, any placement @@ -88,7 +88,8 @@ jfjoch_fpga_stills_test [-i ] [-s ] [-N ] [-B ] [-C - The frames are loaded into the card's internal frame generator and the run is made with the JUNGFRAU conversion off, so the card returns them verbatim; the host assembles them as signed 16-bit photon counts and rugnux live stills analyses them through `FPGAImagePuller`, as the broker does with rugnux live - on (`-d`: not blocking, as the broker runs; `-v`: each card's progress every 0.5 s). Beam centre, distance, energy and the cell + on (`-d`: not blocking, as the broker runs; `-v`: each card's progress every 0.5 s; `-k `: analyse 1 of every + F images on average, the rugnux live setting `stills_downsample`). Beam centre, distance, energy and the cell come from the file (`-C` overrides the cell; without one the frames are indexed de novo). Nothing is written. - Each card's generator holds module frames of its own modules only: as many images as its memory holds diff --git a/frontend/src/client/types.gen.ts b/frontend/src/client/types.gen.ts index 70b47deb5..a08c274a3 100644 --- a/frontend/src/client/types.gen.ts +++ b/frontend/src/client/types.gen.ts @@ -2043,6 +2043,15 @@ export type rugnux_settings = { * */ force_still?: boolean; + /** + * Serial collections: analyse on average 1 of every this many images, to keep up with a fast stream. Each + * image is chosen on its own with probability 1 / stills_downsample from a hash of its number - not a stride, + * which would be in step with periodic patterns (pump-probe on/off, storage cells). The images the pre-pass + * may use (the first 2000) are all analysed. Images not chosen are counted, not analysed and not written. + * 1: every image. + * + */ + stills_downsample?: number; }; export type rugnux_status = { @@ -2066,6 +2075,10 @@ export type rugnux_status = { * DECTRIS rotation collections are processed as stills */ force_still: boolean; + /** + * Serial collections, 1 of every this many images analysed on average + */ + stills_downsample?: number; /** * A model was uploaded with `PUT /config/rugnux/model` */ diff --git a/frontend/src/client/zod.gen.ts b/frontend/src/client/zod.gen.ts index 70749279d..66ef8e861 100644 --- a/frontend/src/client/zod.gen.ts +++ b/frontend/src/client/zod.gen.ts @@ -856,7 +856,8 @@ export const zRugnuxSettings = z.object({ reserved_cpus: z.coerce.bigint().gte(BigInt(0)).max(BigInt('9223372036854775807'), { error: 'Invalid value: Expected int64 to be <= 9223372036854775807' }).optional().default(BigInt(4)), deadline_s: z.number().gte(0).optional().default(60), refine_solvent: z.boolean().optional().default(false), - force_still: z.boolean().optional().default(false) + force_still: z.boolean().optional().default(false), + stills_downsample: z.coerce.bigint().gte(BigInt(1)).max(BigInt('9223372036854775807'), { error: 'Invalid value: Expected int64 to be <= 9223372036854775807' }).optional().default(BigInt(1)) }); export const zRugnuxStatus = z.object({ @@ -865,6 +866,7 @@ export const zRugnuxStatus = z.object({ deadline_s: z.number().optional(), refine_solvent: z.boolean(), force_still: z.boolean(), + stills_downsample: z.coerce.bigint().min(BigInt('-9223372036854775808'), { error: 'Invalid value: Expected int64 to be >= -9223372036854775808' }).max(BigInt('9223372036854775807'), { error: 'Invalid value: Expected int64 to be <= 9223372036854775807' }).optional(), model_loaded: z.boolean(), model_size_bytes: z.coerce.bigint().min(BigInt('-9223372036854775808'), { error: 'Invalid value: Expected int64 to be >= -9223372036854775808' }).max(BigInt('9223372036854775807'), { error: 'Invalid value: Expected int64 to be <= 9223372036854775807' }).optional() }); diff --git a/frontend/src/components/RugnuxSettings.tsx b/frontend/src/components/RugnuxSettings.tsx index 5c7ada58e..5e1a85f2c 100644 --- a/frontend/src/components/RugnuxSettings.tsx +++ b/frontend/src/components/RugnuxSettings.tsx @@ -50,6 +50,8 @@ function RugnuxSettings({measuring}: { measuring: boolean }) { const [cpusError, setCpusError] = useState(false); const [deadline, setDeadline] = useState(0); const [deadlineError, setDeadlineError] = useState(false); + const [downsample, setDownsample] = useState(1); + const [downsampleError, setDownsampleError] = useState(false); const [counter, setCounter] = useState(0); const [file, setFile] = useState(); @@ -60,19 +62,21 @@ function RugnuxSettings({measuring}: { measuring: boolean }) { setForceStill(s.force_still); setCpus(s.reserved_cpus); setDeadline(s.deadline_s ?? 0); + setDownsample(s.stills_downsample ?? 1); setCounter(c => c + 1); } - }, [s?.enable, s?.refine_solvent, s?.force_still, s?.reserved_cpus, s?.deadline_s]); + }, [s?.enable, s?.refine_solvent, s?.force_still, s?.reserved_cpus, s?.deadline_s, s?.stills_downsample]); const dirty = s !== undefined && (enable !== s.enable || refineSolvent !== s.refine_solvent - || forceStill !== s.force_still || cpus !== s.reserved_cpus || deadline !== (s.deadline_s ?? 0)); + || forceStill !== s.force_still || cpus !== s.reserved_cpus || deadline !== (s.deadline_s ?? 0) + || downsample !== (s.stills_downsample ?? 1)); return ( settings.submit({enable, refine_solvent: refineSolvent, force_still: forceStill, - reserved_cpus: cpus, deadline_s: deadline})} - uploadDisabled={measuring || cpusError || deadlineError || settings.pending} + reserved_cpus: cpus, deadline_s: deadline, stills_downsample: downsample})} + uploadDisabled={measuring || cpusError || deadlineError || downsampleError || settings.pending} snackbar={settings.snackbar}> { setDeadline(v); setDeadlineError(err); }}/> + { setDownsample(v); setDownsampleError(err); }}/> diff --git a/receiver/JFJochReceiverRugnuxStills.cpp b/receiver/JFJochReceiverRugnuxStills.cpp index b80066f07..59b634bdb 100644 --- a/receiver/JFJochReceiverRugnuxStills.cpp +++ b/receiver/JFJochReceiverRugnuxStills.cpp @@ -10,6 +10,7 @@ #include "../frame_serialize/CBORStream2Serializer.h" #include "../rugnux/RugnuxDefaults.h" #include "RugnuxStructure.h" +#include "StillsSelection.h" JFJochReceiverRugnuxStills::JFJochReceiverRugnuxStills(const DiffractionExperiment &in_experiment, const PixelMask &in_pixel_mask, @@ -27,13 +28,15 @@ JFJochReceiverRugnuxStills::JFJochReceiverRugnuxStills(const DiffractionExperime ImageBuffer &in_image_buffer, ZMQPreviewSocket *in_zmq_preview_socket, ZMQMetadataSocket *in_zmq_metadata_socket, - IndexerThreadPool *in_indexing_thread_pool) + IndexerThreadPool *in_indexing_thread_pool, + int64_t in_downsample) : JFJochReceiverStream(in_experiment, in_pixel_mask, in_image_puller, in_image_pusher, in_logger, in_forward_nthreads, in_spot_finding_settings, in_current_status, in_plots, in_image_buffer, in_zmq_preview_socket, in_zmq_metadata_socket), model(std::move(in_model)), deadline_s(in_deadline_s), refine_solvent(in_refine_solvent), + downsample(in_downsample), live_status(in_live_status), indexing_thread_pool(in_indexing_thread_pool), stills_nthreads(std::min(16, in_forward_nthreads)) { @@ -81,6 +84,11 @@ void JFJochReceiverRugnuxStills::OnImage(uint32_t id, DataMessage &message, std: } live_status.ImageReceived(received); CountImage(message); + // Not analysed and not written, as an image the serial filter leaves out + if (!StillsImageSelected(message.number, downsample, StillsGPUAnalysis::PREPASS_MAX_IMAGES)) { + ++images_skipped; + return; + } const size_t size = message.image.GetCompressedSize(); // Waits for the analysis in a slot of the image buffer, where it can be seen while it waits (it is not sent from diff --git a/receiver/JFJochReceiverRugnuxStills.h b/receiver/JFJochReceiverRugnuxStills.h index 3f4d8ba4e..b43f1b4c4 100644 --- a/receiver/JFJochReceiverRugnuxStills.h +++ b/receiver/JFJochReceiverRugnuxStills.h @@ -16,6 +16,7 @@ class JFJochReceiverRugnuxStills : public JFJochReceiverStream, public StillsSin const std::shared_ptr model; const double deadline_s; // after the last image, the model step is cut (0 = never) const bool refine_solvent; // the refinement of the placed model builds the solvent + const int64_t downsample; // 1 of every this many images analysed on average (StillsImageSelected) RugnuxLiveStatus &live_status; IndexerThreadPool *const indexing_thread_pool; @@ -58,6 +59,7 @@ public: ImageBuffer &image_buffer, ZMQPreviewSocket *zmq_preview_socket = nullptr, ZMQMetadataSocket *zmq_metadata_socket = nullptr, - IndexerThreadPool *indexing_thread_pool = nullptr); + IndexerThreadPool *indexing_thread_pool = nullptr, + int64_t downsample = 1); ~JFJochReceiverRugnuxStills() override; }; diff --git a/receiver/JFJochReceiverService.cpp b/receiver/JFJochReceiverService.cpp index 378b8a722..07114d667 100644 --- a/receiver/JFJochReceiverService.cpp +++ b/receiver/JFJochReceiverService.cpp @@ -25,7 +25,7 @@ JFJochReceiverService::JFJochReceiverService(AcquisitionDeviceGroup &in_aq_devic JFJochReceiverService &JFJochReceiverService::RugnuxLive(bool enable, std::shared_ptr model, int reserved_cpus, double deadline_s, bool refine_solvent, - bool force_still) { + bool force_still, int64_t stills_downsample) { std::unique_lock ul_state(state_mutex); if (state != ReceiverState::Idle) throw JFJochException(JFJochExceptionCategory::WrongDAQState, @@ -36,6 +36,7 @@ JFJochReceiverService &JFJochReceiverService::RugnuxLive(bool enable, std::share rugnux_deadline_s = deadline_s; rugnux_refine_solvent = refine_solvent; rugnux_force_still = force_still; + rugnux_stills_downsample = stills_downsample; return *this; } @@ -218,7 +219,7 @@ void JFJochReceiverService::Start(const DiffractionExperiment &experiment, experiment, pixel_mask, *image_puller, image_pusher, logger, nthreads, rugnux_model, rugnux_deadline_s, rugnux_refine_solvent, rugnux_status, spot_finding_settings, receiver_status, plots, image_buffer, zmq_preview_socket.get(), zmq_metadata_socket.get(), - indexer_thread_pool.get()); + indexer_thread_pool.get(), rugnux_stills_downsample); else receiver = std::make_unique(experiment, pixel_mask, diff --git a/receiver/JFJochReceiverService.h b/receiver/JFJochReceiverService.h index 2590a30fc..acc361c23 100644 --- a/receiver/JFJochReceiverService.h +++ b/receiver/JFJochReceiverService.h @@ -37,6 +37,7 @@ class JFJochReceiverService { double rugnux_deadline_s = 60; // the analysis is cut this long after the last image (0 = never) bool rugnux_refine_solvent = false; // the refinement of a placed model builds the solvent bool rugnux_force_still = false; // rotation collections from a DECTRIS detector go the stills way + int64_t rugnux_stills_downsample = 1; // serial collections: 1 of every this many images analysed RugnuxLiveStatus rugnux_status; // of the last collection, kept after it ends std::string analysis_warning; // why the collection was not analysed as asked, for the broker's status @@ -71,7 +72,8 @@ public: size_t send_buffer_size_MiB = 512); JFJochReceiverService& NumThreads(int64_t input); JFJochReceiverService& RugnuxLive(bool enable, std::shared_ptr model, int reserved_cpus, - double deadline_s, bool refine_solvent = false, bool force_still = false); + double deadline_s, bool refine_solvent = false, bool force_still = false, + int64_t stills_downsample = 1); RugnuxLiveSnapshot GetRugnuxStatus() const; void ClearRugnuxStatus(); // back to Idle, as before any collection // slots, blocking, frame_rate_hz: see FPGAImagePuller. always: every PSI collection but pedestal and host diff --git a/receiver/StillsSelection.h b/receiver/StillsSelection.h new file mode 100644 index 000000000..2d44fdab8 --- /dev/null +++ b/receiver/StillsSelection.h @@ -0,0 +1,22 @@ +// SPDX-FileCopyrightText: 2026 Filip Leonarski, Paul Scherrer Institute +// SPDX-License-Identifier: GPL-3.0-only + +#pragma once + +#include + +// Rugnux live stills with a downsizing factor F analyse on average 1 of every F images, each image chosen on its +// own with probability 1/F from a hash of its number. A stride would be in step with any period of the stream +// (pump-probe on/off, storage cells, module or card interleave) and could take e.g. only the dark frames; the hash +// is not, and the choice is reproducible and the same on every thread and card. +// The first `all_before` images are all taken: the pre-pass may use any of them. +inline bool StillsImageSelected(int64_t image_number, int64_t factor, int64_t all_before) { + if ((factor <= 1) || (image_number < all_before)) + return true; + // The SplitMix64 finaliser: Steele, Lea & Flood (2014) Proc. OOPSLA 2014, 453-472; salted + uint64_t z = static_cast(image_number) + 0x5d0f3c1a7b2e9d46ULL + 0x9e3779b97f4a7c15ULL; + z = (z ^ (z >> 30)) * 0xbf58476d1ce4e5b9ULL; + z = (z ^ (z >> 27)) * 0x94d049bb133111ebULL; + z = z ^ (z >> 31); + return z % static_cast(factor) == 0; +} diff --git a/tests/CMakeLists.txt b/tests/CMakeLists.txt index d120fcab0..a48a4ac86 100644 --- a/tests/CMakeLists.txt +++ b/tests/CMakeLists.txt @@ -155,6 +155,7 @@ ADD_EXECUTABLE(jfjoch_test JFJochReceiverLiteTest.cpp JFJochReceiverRugnuxTest.cpp FPGAImagePullerTest.cpp + StillsSelectionTest.cpp GridScanSettingsTest.cpp JFJochReceiverPlotsTest.cpp GoniometerAxisTest.cpp diff --git a/tests/StillsSelectionTest.cpp b/tests/StillsSelectionTest.cpp new file mode 100644 index 000000000..7c6800d09 --- /dev/null +++ b/tests/StillsSelectionTest.cpp @@ -0,0 +1,42 @@ +// SPDX-FileCopyrightText: 2026 Filip Leonarski, Paul Scherrer Institute +// SPDX-License-Identifier: GPL-3.0-only + +#include +#include + +#include "../receiver/StillsSelection.h" + +TEST_CASE("StillsImageSelected_FractionAndPeriods", "[StillsSelection]") { + constexpr int64_t first = 2000; + constexpr int64_t images = 400000; + for (const int64_t factor: {2, 3, 4, 10}) { + INFO("factor " << factor); + const double p = 1.0 / static_cast(factor); + int64_t selected = 0; + for (int64_t i = first; i < first + images; i++) + selected += StillsImageSelected(i, factor, first) ? 1 : 0; + // Within 5 standard deviations of the binomial + CHECK(std::abs(static_cast(selected) / images - p) < 5 * std::sqrt(p * (1 - p) / images)); + + // Every phase of a period-2 and a period-F pattern (pump-probe on/off, a stride) gets its share + for (const int64_t period: {int64_t(2), factor}) { + for (int64_t phase = 0; phase < period; phase++) { + INFO("period " << period << " phase " << phase); + int64_t n = 0, s = 0; + for (int64_t i = first + phase; i < first + images; i += period) { + n++; + s += StillsImageSelected(i, factor, first) ? 1 : 0; + } + CHECK(std::abs(static_cast(s) / n - p) < 5 * std::sqrt(p * (1 - p) / n)); + } + } + } +} + +TEST_CASE("StillsImageSelected_DeterministicAndPrePass", "[StillsSelection]") { + for (int64_t i = 0; i < 10000; i++) { + CHECK(StillsImageSelected(i, 1, 0)); // factor 1: every image + CHECK(StillsImageSelected(i, 7, 10000)); // before all_before: every image + CHECK(StillsImageSelected(i, 7, 0) == StillsImageSelected(i, 7, 0)); + } +} diff --git a/tools/jfjoch_fpga_stills_test.cpp b/tools/jfjoch_fpga_stills_test.cpp index 040b1f375..74484ccd3 100644 --- a/tools/jfjoch_fpga_stills_test.cpp +++ b/tools/jfjoch_fpga_stills_test.cpp @@ -40,6 +40,7 @@ void print_usage(Logger &logger) { logger.Info(" -t Indexing thread pool size (default: 4)"); logger.Info(" -r Rates the source is paced at, one collection each (default: 0 = as fast as it goes)"); logger.Info(" -p FPGAImagePuller slots (default 128)"); + logger.Info(" -k Analyse 1 of every images on average (rugnux live stills_downsample, default 1)"); logger.Info(" -d Not blocking, as the broker runs: images the host has no room for are dropped"); logger.Info(" -K{} Mock of the card instead of /dev/jfjoch* (optional: its generator memory, default 64 MiB ="); logger.Info(" 128 module frames)"); @@ -86,7 +87,7 @@ int64_t GeneratorImages(AcquisitionDeviceGroup &aq_devices, const DiffractionExp bool RunDataset(Logger &logger, AcquisitionDeviceGroup &aq_devices, const std::string &file, std::optional nimages, uint16_t nstreams, uint16_t nthreads, size_t send_buffer_size_MiB, const IndexingSettings &indexing, const std::optional &cell, size_t puller_slots, - const std::vector &rates, bool dropping) { + const std::vector &rates, bool dropping, int64_t downsample) { RegisterHDF5Filter(); JFJochHDF5Reader reader; reader.ReadFile(file); @@ -142,7 +143,7 @@ bool RunDataset(Logger &logger, AcquisitionDeviceGroup &aq_devices, const std::s JFJochReceiverService service(aq_devices, logger, pusher, send_buffer_size_MiB); service.NumThreads(nthreads); service.Indexing(x.GetIndexingSettings()); - service.RugnuxLive(true, nullptr, 4, 60); + service.RugnuxLive(true, nullptr, 4, 60, false, false, downsample); // Error, gap and beam-stop pixels of the reader become error pixels of the module frame std::vector frame(x.GetModulesNum() * RAW_MODULE_SIZE); @@ -243,7 +244,8 @@ bool RunDataset(Logger &logger, AcquisitionDeviceGroup &aq_devices, const std::s logger.Info("Pre-pass {:.2f} s: beam {:.2f} {:.2f} px (file {:.2f} {:.2f}), distance {:.2f} mm (file {:.2f})", st.prepass_s.value_or(0), st.beam_x_pxl.value_or(NAN), st.beam_y_pxl.value_or(NAN), st.file_beam_x_pxl, st.file_beam_y_pxl, st.distance_mm.value_or(NAN), st.file_distance_mm); - logger.Info("Analysed {} indexed {} analysis rate after the pre-pass {:.1f} Hz", st.images_analysed, + logger.Info("Analysed {} ({:.3f} of the images) indexed {} analysis rate after the pre-pass {:.1f} Hz", + st.images_analysed, static_cast(st.images_analysed) / x.GetImageNum(), st.images_indexed, after_prepass_hz); } logger.Info("Rugnux: {} {} last image at {:.2f} s, done {:.2f} s after it", live.verdict, live.message, @@ -288,9 +290,10 @@ int main(int argc, char **argv) { bool verbose = false; std::vector rates = {0}; bool dropping = false; + int64_t downsample = 1; int opt; - while ((opt = getopt(argc, argv, "vi:s:N:B:C:X:t:r:p:dK::")) != -1) { + while ((opt = getopt(argc, argv, "vi:s:N:B:C:X:t:r:p:dk:K::")) != -1) { switch (opt) { case 'v': verbose = true; @@ -343,6 +346,9 @@ int main(int argc, char **argv) { case 'd': dropping = true; break; + case 'k': + downsample = atol(optarg); + break; case 'K': mock_card_MiB = (optarg != nullptr) ? atol(optarg) : 64; break; @@ -378,7 +384,7 @@ int main(int argc, char **argv) { bool ret = false; try { ret = RunDataset(logger, aq_devices, argv[optind], nimages, nstreams, nthreads, send_buffer_size_MiB, - i_settings, cell, puller_slots, rates, dropping); + i_settings, cell, puller_slots, rates, dropping, downsample); } catch (std::exception &e) { logger.Error(e.what()); } diff --git a/tools/jfjoch_stills_gpu_replay.cpp b/tools/jfjoch_stills_gpu_replay.cpp index c75647cd9..8fbe645e4 100644 --- a/tools/jfjoch_stills_gpu_replay.cpp +++ b/tools/jfjoch_stills_gpu_replay.cpp @@ -27,6 +27,7 @@ #include "../image_analysis/indexing/IndexerThreadPool.h" #include "../reader/JFJochHDF5Reader.h" #include "../receiver/StillsGPUAnalysis.h" +#include "../receiver/StillsSelection.h" #include "../writer/HDF5Objects.h" #include "../writer/RugnuxModelFile.h" #include "../writer/WriteModel.h" @@ -61,6 +62,7 @@ void print_usage() { std::cout << " -e the first images given as empty frames (no diffraction)" << std::endl; std::cout << " -m model (PDB/mmCIF) placed and refined against the merges" << std::endl; std::cout << " -p spots kept per image (default: the file's, as the broker's)" << std::endl; + std::cout << " -k analyse 1 of every images on average, as rugnux live stills_downsample" << std::endl; std::cout << " -D deadline of the model step after the last image (default 60, 0 = none)" << std::endl; } @@ -84,9 +86,10 @@ int main(int argc, char **argv) { int64_t empty_frames = 0; std::shared_ptr model; double deadline_s = 60; + int64_t downsample = 1; int opt; - while ((opt = getopt(argc, argv, "o:s:n:r:N:b:x:y:C:cFS:Me:m:D:p:")) != -1) { + while ((opt = getopt(argc, argv, "o:s:n:r:N:b:x:y:C:cFS:Me:m:D:p:k:")) != -1) { switch (opt) { case 'o': prefix = optarg; break; case 's': first = atoll(optarg); break; @@ -104,6 +107,7 @@ int main(int argc, char **argv) { case 'e': empty_frames = atoll(optarg); break; case 'm': model = std::make_shared(ReadRugnuxModelFile(optarg)); break; case 'D': deadline_s = atof(optarg); break; + case 'k': downsample = atoll(optarg); break; case 'C': { UnitCell c{}; if (sscanf(optarg, "%f,%f,%f,%f,%f,%f", &c.a, &c.b, &c.c, &c.alpha, &c.beta, &c.gamma) != 6) { @@ -227,6 +231,8 @@ int main(int argc, char **argv) { JFJochReaderRawImage raw; std::vector empty; for (int64_t i = 0; i < n; i++) { + if (!StillsImageSelected(i, downsample, StillsGPUAnalysis::PREPASS_MAX_IMAGES)) + continue; if (rate > 0) std::this_thread::sleep_until(t0 + std::chrono::duration(static_cast(i) / rate)); reader.ReadRawImage(first + i, raw); From bb15ac73cf80340cf0b1f311210391d88d533adb Mon Sep 17 00:00:00 2001 From: Filip Leonarski Date: Wed, 18 Nov 2026 12:38:37 +0100 Subject: [PATCH 17/41] Space group: one stored in a data file is ignored, one given for the collection is binding - rugnux (mx mode) already cleared the file's space group and cell (ClearStoredCrystal, since rc161); it now says so in the log when the file had a space group and no -S was given. - jfjoch_stills_gpu_replay and jfjoch_fpga_stills_test built the collection's start message from the file and so carried the file's space group into the live merge as if the user had given it. Now only -S gives one (new in the stills test); the file's is ignored with a log line. - The live path is unchanged: the space group of the start message (the dataset settings) is what the merge uses, as given. - --mode scale keeps taking the group a _process.h5 was written in: rugnux's own output, its reflections already indexed in it. - No battery row depended on the file's space group: the battery runs mx mode. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01UqXYdHHZ4cogS1mrGUtfN7 --- docs/JFJOCH_BROKER.md | 2 +- docs/RUGNUX_CLI.md | 2 +- rugnux/rugnux_cli.cpp | 4 ++++ tools/jfjoch_fpga_stills_test.cpp | 26 +++++++++++++++++++++----- tools/jfjoch_stills_gpu_replay.cpp | 8 +++++--- 5 files changed, 32 insertions(+), 10 deletions(-) diff --git a/docs/JFJOCH_BROKER.md b/docs/JFJOCH_BROKER.md index 9cef7084f..4f495b651 100644 --- a/docs/JFJOCH_BROKER.md +++ b/docs/JFJOCH_BROKER.md @@ -383,7 +383,7 @@ next `/start` runs as usual. The indexed frames are also merged, as `rugnux --mode scale` merges stills, in memory - in the consensus cell of the frames indexed by the first merge (the cell of the dataset settings only picks the frames that are -merged) and the space group of the dataset settings (else P1). +merged) and the space group of the dataset settings (else P1): a space group given for the collection is binding. At half and at three quarters of the images the frames so far are merged beside the analysis, on 8 threads, and the result is reported as a provisional step note: crystals, resolution, CC1/2, R_split, completeness and ⟨I/σ⟩. The first of these merges scales and post-refines every crystal so far and decides the indexing diff --git a/docs/RUGNUX_CLI.md b/docs/RUGNUX_CLI.md index a85be37f6..f03a83c15 100644 --- a/docs/RUGNUX_CLI.md +++ b/docs/RUGNUX_CLI.md @@ -286,7 +286,7 @@ For very long axes the direction grid's angular resolution binds well below 500 | `-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 this cell and `-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)). Without `-C` the group fixes only the symmetry, not the cell: the lattice is found and reduced as in a run without `-S` (a supercell the indexer returns is still stepped down to the crystal's cell, a long axis is still looked for), indexing puts the crystal in the group's own Bravais class, nothing promotes or demotes it past that class, and the group is applied to the cell found, in its conventional setting. With `-C` as well, the lattice and its setting are the ones given and nothing reduces or doubles the cell. 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`, the cell is written on the given cell's axes | +| `-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)). Without `-C` the group fixes only the symmetry, not the cell: the lattice is found and reduced as in a run without `-S` (a supercell the indexer returns is still stepped down to the crystal's cell, a long axis is still looked for), indexing puts the crystal in the group's own Bravais class, nothing promotes or demotes it past that class, and the group is applied to the cell found, in its conventional setting. With `-C` as well, the lattice and its setting are the ones given and nothing reduces or doubles the cell. 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`, the cell is written on the given cell's axes. A space group (and a cell) stored in the input file is ignored, with a line in the log saying so: only `-S` (and `-C`) fix them (`--mode scale` takes the group a `_process.h5` was written in) | | `-r, --geom-refine ` | Geometry refinement: `none` \| `orientation` \| `beam_and_lattice` (default; on rotation data restrained toward the sweep's geometry, [§7.4](CPU_DATA_ANALYSIS_INDEXING.md#74-multi-stage-tightening-of-inlier-tolerance)) \| `flex` (try all three per image, keep whichever indexes the most spots; alias `multi`) | | `-R, --two-pass-rotation[=num]` | Two-pass offline rotation indexing (default for goniometer data; optional first-pass image count, default 100) | | `--force-rotation-lattice ` | Force rotation lattice (9 floats, Ã…), skipping the first pass | diff --git a/rugnux/rugnux_cli.cpp b/rugnux/rugnux_cli.cpp index ce53e8431..f8f180ba4 100644 --- a/rugnux/rugnux_cli.cpp +++ b/rugnux/rugnux_cli.cpp @@ -3485,6 +3485,10 @@ int RugnuxInputRun::PrepareRugnuxInput() { // configure_offline_output applies the rugnux analysis defaults, one of which is the polarization // factor, so an explicit --polarization has to land after it or it is silently overwritten. if (polarization_factor) experiment.PolarizationFactor(polarization_factor.value()); + // A space group stored in the data file is not the user's: only -S fixes one + if (space_group == nullptr && experiment.GetGemmiSpaceGroup()) + logger.Info("Space group {} stored in the input file is ignored; -S fixes the space group", + experiment.GetGemmiSpaceGroup()->hm); ClearStoredCrystal(experiment); // shared with the viewer; -S / -C below override it if (space_group != nullptr) experiment.SetSpaceGroup(*space_group); diff --git a/tools/jfjoch_fpga_stills_test.cpp b/tools/jfjoch_fpga_stills_test.cpp index 74484ccd3..a7359dcf7 100644 --- a/tools/jfjoch_fpga_stills_test.cpp +++ b/tools/jfjoch_fpga_stills_test.cpp @@ -36,6 +36,7 @@ void print_usage(Logger &logger) { logger.Info(" -N Number of image processing threads (default 64)"); logger.Info(" -B Size of the image buffer in MiB (default 16384)"); logger.Info(" -C Unit cell (default: the file's)"); + logger.Info(" -S Space group of the collection (a space group stored in the file is ignored)"); logger.Info(" -X Indexing (auto|fft|fftw|ffbidx), auto is default"); logger.Info(" -t Indexing thread pool size (default: 4)"); logger.Info(" -r Rates the source is paced at, one collection each (default: 0 = as fast as it goes)"); @@ -87,7 +88,8 @@ int64_t GeneratorImages(AcquisitionDeviceGroup &aq_devices, const DiffractionExp bool RunDataset(Logger &logger, AcquisitionDeviceGroup &aq_devices, const std::string &file, std::optional nimages, uint16_t nstreams, uint16_t nthreads, size_t send_buffer_size_MiB, const IndexingSettings &indexing, const std::optional &cell, size_t puller_slots, - const std::vector &rates, bool dropping, int64_t downsample) { + const std::vector &rates, bool dropping, int64_t downsample, + const std::optional &space_group) { RegisterHDF5Filter(); JFJochHDF5Reader reader; reader.ReadFile(file); @@ -113,8 +115,12 @@ bool RunDataset(Logger &logger, AcquisitionDeviceGroup &aq_devices, const std::s x.IncidentEnergy_keV(file_x.GetIncidentEnergy_keV()).DetectorDistance_mm(file_x.GetDetectorDistance_mm()) .BeamX_pxl(file_x.GetBeamX_pxl()).BeamY_pxl(file_x.GetBeamY_pxl()); x.SetUnitCell(cell ? cell : file_x.GetUnitCell()); - if (file_x.GetSpaceGroupNumber()) - x.SetSpaceGroup(file_x.GetSpaceGroupOrP1()); + // A space group stored in the file is ignored: only -S gives one, as the user gives it for a collection + if (space_group) + x.SetSpaceGroup(*space_group); + else if (file_x.GetGemmiSpaceGroup()) + logger.Info("Space group {} stored in the file is ignored; -S gives the collection one", + file_x.GetGemmiSpaceGroup()->hm); x.ImportIndexingSettings(indexing); const int64_t generator_images = GeneratorImages(aq_devices, x, reader.GetNumberOfImages()); @@ -291,9 +297,10 @@ int main(int argc, char **argv) { std::vector rates = {0}; bool dropping = false; int64_t downsample = 1; + std::optional space_group; int opt; - while ((opt = getopt(argc, argv, "vi:s:N:B:C:X:t:r:p:dk:K::")) != -1) { + while ((opt = getopt(argc, argv, "vi:s:N:B:C:S:X:t:r:p:dk:K::")) != -1) { switch (opt) { case 'v': verbose = true; @@ -349,6 +356,15 @@ int main(int argc, char **argv) { case 'k': downsample = atol(optarg); break; + case 'S': { + const gemmi::SpaceGroup *sg = gemmi::find_spacegroup_by_name(optarg); + if (sg == nullptr) { + print_usage(logger); + exit(EXIT_FAILURE); + } + space_group = *sg; + break; + } case 'K': mock_card_MiB = (optarg != nullptr) ? atol(optarg) : 64; break; @@ -384,7 +400,7 @@ int main(int argc, char **argv) { bool ret = false; try { ret = RunDataset(logger, aq_devices, argv[optind], nimages, nstreams, nthreads, send_buffer_size_MiB, - i_settings, cell, puller_slots, rates, dropping, downsample); + i_settings, cell, puller_slots, rates, dropping, downsample, space_group); } catch (std::exception &e) { logger.Error(e.what()); } diff --git a/tools/jfjoch_stills_gpu_replay.cpp b/tools/jfjoch_stills_gpu_replay.cpp index 8fbe645e4..3a18fc439 100644 --- a/tools/jfjoch_stills_gpu_replay.cpp +++ b/tools/jfjoch_stills_gpu_replay.cpp @@ -57,7 +57,7 @@ void print_usage() { std::cout << " -C unit cell of the collection" << std::endl; std::cout << " -F the broker's default fixed-threshold spot finder (default: adaptive, as the receiver)" << std::endl; std::cout << " -c leave the file's unit cell out of the collection" << std::endl; - std::cout << " -S space group of the collection (the merge's)" << std::endl; + std::cout << " -S space group of the collection, the merge's (a space group stored in the file is ignored)" << std::endl; std::cout << " -M no merge (StillsGPUAnalysis merge = false)" << std::endl; std::cout << " -e the first images given as empty frames (no diffraction)" << std::endl; std::cout << " -m model (PDB/mmCIF) placed and refined against the merges" << std::endl; @@ -149,8 +149,10 @@ int main(int argc, char **argv) { x.SetUnitCell(cell); if (max_spots) x.MaxSpotCount(*max_spots); - if (space_group) - x.SetSpaceGroup(*gemmi::find_spacegroup_by_name(*space_group)); + // A space group stored in the file is ignored: only -S gives one, as the user gives it for a collection + if (!space_group && x.GetGemmiSpaceGroup()) + logger.Info("Space group {} stored in the file is ignored; -S gives the collection one", x.GetGemmiSpaceGroup()->hm); + x.SetSpaceGroup(space_group ? std::optional(*gemmi::find_spacegroup_by_name(*space_group)) : std::nullopt); const PixelMask &mask = *dataset->pixel_mask; StartMessage start; From 536f83e28fd7841b5d2b9c64191636410671a02a Mon Sep 17 00:00:00 2001 From: Filip Leonarski Date: Wed, 18 Nov 2026 13:08:09 +0100 Subject: [PATCH 18/41] max_spot_count optional: 250 for the per-image indexing, 1000 for rugnux live stills where not given dataset_settings.max_spot_count loses its default in OpenAPI and becomes optional in DatasetSettings. Left out, the broker's per-image indexing (JFJochReceiverFPGA, JFJochReceiverLite) keeps DEFAULT_MAX_SPOT_COUNT = 250, as before; rugnux live stills takes rugnux's default, the budget the pre-pass measures up to 1000. Given, both use it: the pre-pass keeps it as `rugnux --max-spots` does (no budget measured) and the frames after it are indexed on it. Before, live stills always took 1000 (lane l, 17bfca6a2), whatever was given. C++ model, frontend client and the python client's docs regenerated (the python-client package itself is built at release by update_version.sh); OpenAPIConvert sets it only where given; the frontend builds. The stills replay's -p default is now that of rugnux live. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01UqXYdHHZ4cogS1mrGUtfN7 --- broker/OpenAPIConvert.cpp | 3 ++- broker/gen/model/Dataset_settings.cpp | 2 +- broker/gen/model/Dataset_settings.h | 2 +- broker/jfjoch_api.yaml | 5 +++-- common/DatasetSettings.cpp | 5 ++++- common/DatasetSettings.h | 5 +++-- common/Definitions.h | 2 ++ common/DiffractionExperiment.cpp | 4 ++++ common/DiffractionExperiment.h | 1 + docs/JFJOCH_BROKER.md | 3 +++ docs/python_client/docs/DatasetSettings.md | 2 +- docs/python_client/docs/RugnuxSettings.md | 1 + docs/python_client/docs/RugnuxStatus.md | 1 + frontend/src/client/types.gen.ts | 8 ++++++-- frontend/src/client/zod.gen.ts | 4 ++-- receiver/StillsGPUAnalysis.cpp | 9 ++++++--- receiver/StillsPrePass.cpp | 4 ++-- receiver/StillsPrePass.h | 3 ++- rugnux/RugnuxLive.cpp | 8 +++++--- rugnux/RugnuxLive.h | 4 +++- tests/DiffractionExperimentTest.cpp | 10 ++++++++++ tools/jfjoch_stills_gpu_replay.cpp | 2 +- 22 files changed, 64 insertions(+), 24 deletions(-) diff --git a/broker/OpenAPIConvert.cpp b/broker/OpenAPIConvert.cpp index 07a92ed97..da03e86ff 100644 --- a/broker/OpenAPIConvert.cpp +++ b/broker/OpenAPIConvert.cpp @@ -728,7 +728,8 @@ DatasetSettings Convert(const org::openapitools::server::model::Dataset_settings ret.SampleTemperature_K(input.getSampleTemperatureK()); ret.SpotFindingEnable(input.isSpotFinding()); - ret.MaxSpotCount(input.getMaxSpotCount()); + if (input.maxSpotCountIsSet()) + ret.MaxSpotCount(input.getMaxSpotCount()); if (input.detectIceRingsIsSet()) ret.DetectIceRings(input.isDetectIceRings()); diff --git a/broker/gen/model/Dataset_settings.cpp b/broker/gen/model/Dataset_settings.cpp index 391b1a2fc..7cabe1fdd 100644 --- a/broker/gen/model/Dataset_settings.cpp +++ b/broker/gen/model/Dataset_settings.cpp @@ -85,7 +85,7 @@ Dataset_settings::Dataset_settings() m_Spot_finding = true; m_Spot_findingIsSet = false; m_SmargonIsSet = false; - m_Max_spot_count = 250; + m_Max_spot_count = 0; m_Max_spot_countIsSet = false; m_Detect_ice_rings = false; m_Detect_ice_ringsIsSet = false; diff --git a/broker/gen/model/Dataset_settings.h b/broker/gen/model/Dataset_settings.h index 4c6cec660..5c9a220e5 100644 --- a/broker/gen/model/Dataset_settings.h +++ b/broker/gen/model/Dataset_settings.h @@ -318,7 +318,7 @@ public: bool smargonIsSet() const; void unsetSmargon(); /// - /// Maximum number of spots that are saved/used for indexing; spots with highest intensity are selected + /// Maximum number of spots that are saved/used for indexing; spots with highest intensity are selected. Left out, the broker's per-image indexing keeps 250 and rugnux live stills 1000. /// int32_t getMaxSpotCount() const; void setMaxSpotCount(int32_t const value); diff --git a/broker/jfjoch_api.yaml b/broker/jfjoch_api.yaml index eae6e7825..e74abf13d 100644 --- a/broker/jfjoch_api.yaml +++ b/broker/jfjoch_api.yaml @@ -667,8 +667,9 @@ components: type: integer minimum: 10 maximum: 2000 - default: 250 - description: Maximum number of spots that are saved/used for indexing; spots with highest intensity are selected + description: | + Maximum number of spots that are saved/used for indexing; spots with highest intensity are selected. + Left out, the broker's per-image indexing keeps 250 and rugnux live stills 1000. detect_ice_rings: type: boolean description: | diff --git a/common/DatasetSettings.cpp b/common/DatasetSettings.cpp index 601b5114b..97501d354 100644 --- a/common/DatasetSettings.cpp +++ b/common/DatasetSettings.cpp @@ -29,7 +29,6 @@ DatasetSettings::DatasetSettings() { poni_rot_2_rad = 0.0f; poni_rot_3_rad = 0.0f; - max_spot_count = std::min(MAX_SPOT_COUNT, 250); } DatasetSettings &DatasetSettings::ImagesPerTrigger(int64_t input) { @@ -557,6 +556,10 @@ const XrayFluorescenceSpectrum & DatasetSettings::GetFluorescenceSpectrum() cons } int64_t DatasetSettings::GetMaxSpotCount() const { + return max_spot_count.value_or(DEFAULT_MAX_SPOT_COUNT); +} + +std::optional DatasetSettings::GetMaxSpotCountGiven() const { return max_spot_count; } diff --git a/common/DatasetSettings.h b/common/DatasetSettings.h index 208c521ca..e0d88c8c2 100644 --- a/common/DatasetSettings.h +++ b/common/DatasetSettings.h @@ -73,7 +73,7 @@ class DatasetSettings { float poni_rot_3_rad; bool spot_finding_enable; - int64_t max_spot_count; + std::optional max_spot_count; // unset: each analysis takes its own default // Special handling of ice rings; unset where the user did not ask either way, so that the analysis takes its own // default (rugnux: on for a rotation sweep, off for stills) and the master file carries no detect_ice_rings @@ -186,7 +186,8 @@ public: std::optional GetSampleTemperature_K() const; bool IsSpotFindingEnabled() const; - int64_t GetMaxSpotCount() const; + int64_t GetMaxSpotCount() const; // DEFAULT_MAX_SPOT_COUNT where none is given + std::optional GetMaxSpotCountGiven() const; bool IsDetectIceRings() const; // false where unset std::optional GetDetectIceRings() const; diff --git a/common/Definitions.h b/common/Definitions.h index 6380efae5..ffdc0073b 100644 --- a/common/Definitions.h +++ b/common/Definitions.h @@ -47,6 +47,8 @@ constexpr float DEFAULT_G2_FACTOR = -0.1145f; constexpr float DEFAULT_HG0_FACTOR = 100.0f; constexpr int MAX_SPOT_COUNT = 64 * 1024; +// Spots kept per image where none is given: the broker's per-image indexing (rugnux live stills takes its own default) +constexpr int DEFAULT_MAX_SPOT_COUNT = 250; // Three spots fit any lattice at all; one short of ViableCellMinSpots (default 9) is where a fitted // lattice stops being distinguishable from a random one, so a spot list shorter than this is never diff --git a/common/DiffractionExperiment.cpp b/common/DiffractionExperiment.cpp index e7917d146..b4a20a48b 100644 --- a/common/DiffractionExperiment.cpp +++ b/common/DiffractionExperiment.cpp @@ -599,6 +599,10 @@ DiffractionExperiment &DiffractionExperiment::MaxSpotCount(int64_t input) { return *this; } +std::optional DiffractionExperiment::GetMaxSpotCountGiven() const { + return dataset.GetMaxSpotCountGiven(); +} + int64_t DiffractionExperiment::GetMaxSpotCount() const { if (!IsSpotFindingEnabled()) return 0; diff --git a/common/DiffractionExperiment.h b/common/DiffractionExperiment.h index f45e08fcd..c55444a93 100644 --- a/common/DiffractionExperiment.h +++ b/common/DiffractionExperiment.h @@ -305,6 +305,7 @@ public: int64_t GetStorageCellStart() const; int64_t GetMaxSpotCount() const; + std::optional GetMaxSpotCountGiven() const; // as the user gave it, unset where not float GetPixelSize_mm() const; std::string GetSourceName() const; diff --git a/docs/JFJOCH_BROKER.md b/docs/JFJOCH_BROKER.md index 4f495b651..24599c00f 100644 --- a/docs/JFJOCH_BROKER.md +++ b/docs/JFJOCH_BROKER.md @@ -381,6 +381,9 @@ mask in use. Where the start message cannot be sent after the pre-pass (no write cannot be set up, the collection ends with that error, reported by `/status` and `/wait_till_done`, and the next `/start` runs as usual. +The frames are indexed on at most `max_spot_count` spots of the dataset settings where it is given; left out, on as +many as the pre-pass measured (at most 1000, as `rugnux`), while the per-image analysis without rugnux live keeps 250. + The indexed frames are also merged, as `rugnux --mode scale` merges stills, in memory - in the consensus cell of the frames indexed by the first merge (the cell of the dataset settings only picks the frames that are merged) and the space group of the dataset settings (else P1): a space group given for the collection is binding. diff --git a/docs/python_client/docs/DatasetSettings.md b/docs/python_client/docs/DatasetSettings.md index 494ce80f8..27869f1dc 100644 --- a/docs/python_client/docs/DatasetSettings.md +++ b/docs/python_client/docs/DatasetSettings.md @@ -42,7 +42,7 @@ Name | Type | Description | Notes **unit_cell** | [**UnitCell**](UnitCell.md) | | [optional] **spot_finding** | **bool** | Enable spot finding and save spots | [optional] [default to True] **smargon** | [**DatasetSettingsSmargon**](DatasetSettingsSmargon.md) | | [optional] -**max_spot_count** | **int** | Maximum number of spots that are saved/used for indexing; spots with highest intensity are selected | [optional] [default to 250] +**max_spot_count** | **int** | Maximum number of spots that are saved/used for indexing; spots with highest intensity are selected. Left out, the broker's per-image indexing keeps 250 and rugnux live stills 1000. | [optional] **detect_ice_rings** | **bool** | Flag spots as ice rings and reduce their effect on indexing. Left out, the broker's own spot finding treats no spot as an ice ring, rugnux live decides as a bare `rugnux` would (on for a rotation sweep, off for stills), and the master file carries no `detect_ice_rings`. | [optional] **async_start** | **bool** | When set to true, `/start` will not wait for detector and Jungfraujoch to be ready for the measurement. | [optional] [default to False] **module_placement** | [**List[DetectorModulePlacement]**](DetectorModulePlacement.md) | Where the detector's modules lie for this dataset, as rugnux measures them: rugnux writes `<prefix>_module_placement.json`, which holds exactly this field, to be merged into the dataset settings. Each entry names its module by its readout pixel 0 and readout axes in the stored image (`x0`, `y0`, `fast_axis`, `slow_axis`, after `mirror_y`; see `detector_module_placement`), in any order; every module must be named once, and only modules of the detector, else `/start` fails with 400. The image is assembled as configured (`custom_geometry`); the placement goes into the start message and the NXmx `module_NN` groups, and the analysis takes it. Omitted or empty: modules as assembled. | [optional] diff --git a/docs/python_client/docs/RugnuxSettings.md b/docs/python_client/docs/RugnuxSettings.md index 30fa79529..f804fc37a 100644 --- a/docs/python_client/docs/RugnuxSettings.md +++ b/docs/python_client/docs/RugnuxSettings.md @@ -11,6 +11,7 @@ Name | Type | Description | Notes **deadline_s** | **float** | Fixed cutoff: this long after the last image the analysis is cut, and the collection ends with what it has established (as `POST /cancel` after the last image does). 0 means no cutoff. | [optional] [default to 60.0] **refine_solvent** | **bool** | With a model: the refinement also builds the solvent - waters added at difference-map peaks and removed where the maps no longer hold them, waters and ions relabelled (as `rugnux --refine-solvent`). Reset to false by `POST /initialize`. | [optional] [default to False] **force_still** | **bool** | Process DECTRIS rotation collections as stills, on the serial path (pre-pass, GPU analysis, stills merge), as `rugnux --force-still` does. The written file keeps its goniometer. Reset to false by `POST /initialize`. | [optional] [default to False] +**stills_downsample** | **int** | Serial collections: analyse on average 1 of every this many images, to keep up with a fast stream. Each image is chosen on its own with probability 1 / stills_downsample from a hash of its number - not a stride, which would be in step with periodic patterns (pump-probe on/off, storage cells). The images the pre-pass may use (the first 2000) are all analysed. Images not chosen are counted, not analysed and not written. 1: every image. | [optional] [default to 1] ## Example diff --git a/docs/python_client/docs/RugnuxStatus.md b/docs/python_client/docs/RugnuxStatus.md index 043cf872c..20ad3e09e 100644 --- a/docs/python_client/docs/RugnuxStatus.md +++ b/docs/python_client/docs/RugnuxStatus.md @@ -10,6 +10,7 @@ Name | Type | Description | Notes **deadline_s** | **float** | Seconds after the last image at which the analysis is cut; 0 means no cutoff | [optional] **refine_solvent** | **bool** | The refinement of a placed model also builds the solvent | **force_still** | **bool** | DECTRIS rotation collections are processed as stills | +**stills_downsample** | **int** | Serial collections, 1 of every this many images analysed on average | [optional] **model_loaded** | **bool** | A model was uploaded with `PUT /config/rugnux/model` | **model_size_bytes** | **int** | Size of the uploaded model file | [optional] diff --git a/frontend/src/client/types.gen.ts b/frontend/src/client/types.gen.ts index a08c274a3..fc32c424a 100644 --- a/frontend/src/client/types.gen.ts +++ b/frontend/src/client/types.gen.ts @@ -382,7 +382,9 @@ export type dataset_settings = { ]; }; /** - * Maximum number of spots that are saved/used for indexing; spots with highest intensity are selected + * Maximum number of spots that are saved/used for indexing; spots with highest intensity are selected. + * Left out, the broker's per-image indexing keeps 250 and rugnux live stills 1000. + * */ max_spot_count?: number; /** @@ -2855,7 +2857,9 @@ export type dataset_settingsWritable = { ]; }; /** - * Maximum number of spots that are saved/used for indexing; spots with highest intensity are selected + * Maximum number of spots that are saved/used for indexing; spots with highest intensity are selected. + * Left out, the broker's per-image indexing keeps 250 and rugnux live stills 1000. + * */ max_spot_count?: number; /** diff --git a/frontend/src/client/zod.gen.ts b/frontend/src/client/zod.gen.ts index 66ef8e861..6998b74e5 100644 --- a/frontend/src/client/zod.gen.ts +++ b/frontend/src/client/zod.gen.ts @@ -752,7 +752,7 @@ export const zDatasetSettings = z.object({ 1 ]) }).optional(), - max_spot_count: z.int().gte(10).lte(2000).optional().default(250), + max_spot_count: z.int().gte(10).lte(2000).optional(), detect_ice_rings: z.boolean().optional(), async_start: z.boolean().optional().default(false), module_placement: z.array(zDetectorModulePlacement).optional(), @@ -1228,7 +1228,7 @@ export const zDatasetSettingsWritable = z.object({ 1 ]) }).optional(), - max_spot_count: z.int().gte(10).lte(2000).optional().default(250), + max_spot_count: z.int().gte(10).lte(2000).optional(), detect_ice_rings: z.boolean().optional(), async_start: z.boolean().optional().default(false), module_placement: z.array(zDetectorModulePlacement).optional(), diff --git a/receiver/StillsGPUAnalysis.cpp b/receiver/StillsGPUAnalysis.cpp index 57f400846..83ea397b0 100644 --- a/receiver/StillsGPUAnalysis.cpp +++ b/receiver/StillsGPUAnalysis.cpp @@ -191,7 +191,8 @@ void StillsGPUAnalysis::PrePassThread() { Publish(); try { const auto t0 = std::chrono::steady_clock::now(); - auto ret = RunStillsPrePass(start, sample, static_cast(std::thread::hardware_concurrency())); + auto ret = RunStillsPrePass(start, sample, static_cast(std::thread::hardware_concurrency()), + experiment.GetMaxSpotCountGiven()); logger.Info("Pre-pass on {} images ({:.1f} s): beam centre ({:.2f}, {:.2f}) -> ({:.2f}, {:.2f}) px, " "distance {:.2f} -> {:.2f} mm on {} frames, masked pixels {} -> {}", ret.images, std::chrono::duration(std::chrono::steady_clock::now() - t0).count(), @@ -218,14 +219,16 @@ void StillsGPUAnalysis::PrePassThread() { } const bool failed = !result; int geometry_frames = 0; + // Spots kept per frame: as given for the collection, else rugnux's default (below: the budget the pre-pass kept) + setup.experiment.MaxSpotCount(experiment.GetMaxSpotCountGiven().value_or(RUGNUX_MAX_SPOT_COUNT)); if (result) { setup.experiment.BeamX_pxl(result->beam_x_pxl).BeamY_pxl(result->beam_y_pxl).DetectorDistance_mm(result->distance_mm); // The frames are indexed on the cell refined beside that distance, as offline: the stated cell at the refined // distance is off in scale by as much as the distance moved (1.7% on a set whose header was that far off) if (result->cell) setup.experiment.SetUnitCell(*result->cell); - // and on as many spots as the pre-pass kept, as offline (the broker's default of 250 left a 9M frame of - // ~380 spots a third short of what its lattice is refined on) + // and on as many spots as the pre-pass kept, as offline: the count given, or the budget it measured (the + // broker's per-image default of 250 left a 9M frame of ~380 spots a third short of what its lattice is refined on) setup.experiment.MaxSpotCount(result->max_spot_count); // The frames are integrated as the pre-pass integrated its own: its polarization and background ring setup.experiment.PolarizationFactor(result->polarization); diff --git a/receiver/StillsPrePass.cpp b/receiver/StillsPrePass.cpp index 5f5eb7bf2..e759193f3 100644 --- a/receiver/StillsPrePass.cpp +++ b/receiver/StillsPrePass.cpp @@ -44,10 +44,10 @@ namespace { } StillsPrePassResult RunStillsPrePass(const StartMessage &start, const std::map> &images, - int nthreads) { + int nthreads, std::optional max_spot_count) { HeldImageReader reader(start, images); const auto dataset = reader.GetDataset(); - const RugnuxLiveSetup setup = MakeRugnuxStillsPrePassSetup(*dataset, nthreads); + const RugnuxLiveSetup setup = MakeRugnuxStillsPrePassSetup(*dataset, nthreads, max_spot_count); Rugnux rugnux(reader, setup.experiment, *dataset->pixel_mask, setup.config); const ProcessResult result = rugnux.Run(); diff --git a/receiver/StillsPrePass.h b/receiver/StillsPrePass.h index 2a3765664..5f6712c15 100644 --- a/receiver/StillsPrePass.h +++ b/receiver/StillsPrePass.h @@ -57,5 +57,6 @@ struct StillsPrePassResult { // The first frames of a serial collection through rugnux: beam centre, distance (with a cell), mask and // integration settings it decides +// max_spot_count: as given for the collection (DiffractionExperiment::GetMaxSpotCountGiven) StillsPrePassResult RunStillsPrePass(const StartMessage &start, const std::map> &images, - int nthreads); + int nthreads, std::optional max_spot_count = {}); diff --git a/rugnux/RugnuxLive.cpp b/rugnux/RugnuxLive.cpp index ec93ee2e3..24e94691e 100644 --- a/rugnux/RugnuxLive.cpp +++ b/rugnux/RugnuxLive.cpp @@ -66,7 +66,8 @@ RugnuxLiveSetup MakeRugnuxLiveSetup(const JFJochReaderDataset &dataset, int nthr return s; } -RugnuxLiveSetup MakeRugnuxStillsPrePassSetup(const JFJochReaderDataset &dataset, int nthreads) { +RugnuxLiveSetup MakeRugnuxStillsPrePassSetup(const JFJochReaderDataset &dataset, int nthreads, + std::optional max_spot_count) { RugnuxLiveSetup s; // The experiment as rugnux_cli.cpp sets it up for serial data with no options given. @@ -74,7 +75,7 @@ RugnuxLiveSetup MakeRugnuxStillsPrePassSetup(const JFJochReaderDataset &dataset, x = dataset.experiment; ApplyRugnuxExperimentDefaults(x); x.NumTriggers(1); - x.MaxSpotCount(RUGNUX_MAX_SPOT_COUNT); + x.MaxSpotCount(max_spot_count.value_or(RUGNUX_MAX_SPOT_COUNT)); IndexingSettings indexing; indexing.Algorithm(IndexingAlgorithmEnum::Auto); @@ -97,7 +98,8 @@ RugnuxLiveSetup MakeRugnuxStillsPrePassSetup(const JFJochReaderDataset &dataset, c.detect_beam_stop = RUGNUX_DETECT_BEAM_STOP_FRAMES; c.beam_center_check = true; c.adaptive_integration_radius = true; - c.measure_spot_budget = true; + // A count given is kept, as `rugnux --max-spots` keeps it + c.measure_spot_budget = !max_spot_count.has_value(); // As `rugnux -C`: the geometry bundle adjustment needs the cell. if (x.GetUnitCell().has_value()) c.refine_geometry = RUGNUX_REFINE_GEOMETRY_FRAMES; diff --git a/rugnux/RugnuxLive.h b/rugnux/RugnuxLive.h index 73479041e..24f93de8e 100644 --- a/rugnux/RugnuxLive.h +++ b/rugnux/RugnuxLive.h @@ -23,7 +23,9 @@ RugnuxLiveSetup MakeRugnuxLiveSetup(const JFJochReaderDataset &dataset, int nthr // The first frames of a serial collection, processed inside the broker before the rest are analysed: // what a bare `rugnux --no-merge` (with -C where the collection states a cell) on those frames sets. // The run's beam centre and mask are what the broker then analyses the whole collection with. -RugnuxLiveSetup MakeRugnuxStillsPrePassSetup(const JFJochReaderDataset &dataset, int nthreads); +// max_spot_count: as the user gave it for the collection; unset, rugnux's default, the budget measured as rugnux does +RugnuxLiveSetup MakeRugnuxStillsPrePassSetup(const JFJochReaderDataset &dataset, int nthreads, + std::optional max_spot_count = {}); // Builds on every card, at the same time, the GPU FFT indexers a live run of this setup is known to // need - its first pass's (the settings Rugnux gives it) - and the cuFFT diff --git a/tests/DiffractionExperimentTest.cpp b/tests/DiffractionExperimentTest.cpp index 606a59d16..a5e2c172b 100644 --- a/tests/DiffractionExperimentTest.cpp +++ b/tests/DiffractionExperimentTest.cpp @@ -1334,3 +1334,13 @@ TEST_CASE("DiffractionExperiment_AzIntegration_QBinning_OpenAPI", "[DiffractionE Catch::Matchers::ContainsSubstring("only to linear")); } } + +TEST_CASE("DiffractionExperiment_MaxSpotCountGiven","[DiffractionExperiment]") { + DiffractionExperiment x; + // Not given: each analysis takes its own default, the per-image indexing DEFAULT_MAX_SPOT_COUNT + CHECK(!x.GetMaxSpotCountGiven().has_value()); + CHECK(x.GetMaxSpotCount() == DEFAULT_MAX_SPOT_COUNT); + x.MaxSpotCount(700); + CHECK(x.GetMaxSpotCountGiven() == 700); + CHECK(x.GetMaxSpotCount() == 700); +} diff --git a/tools/jfjoch_stills_gpu_replay.cpp b/tools/jfjoch_stills_gpu_replay.cpp index 3a18fc439..99b1ddae4 100644 --- a/tools/jfjoch_stills_gpu_replay.cpp +++ b/tools/jfjoch_stills_gpu_replay.cpp @@ -61,7 +61,7 @@ void print_usage() { std::cout << " -M no merge (StillsGPUAnalysis merge = false)" << std::endl; std::cout << " -e the first images given as empty frames (no diffraction)" << std::endl; std::cout << " -m model (PDB/mmCIF) placed and refined against the merges" << std::endl; - std::cout << " -p spots kept per image (default: the file's, as the broker's)" << std::endl; + std::cout << " -p spots kept per image (default: as rugnux live stills where none is given, 1000)" << std::endl; std::cout << " -k analyse 1 of every images on average, as rugnux live stills_downsample" << std::endl; std::cout << " -D deadline of the model step after the last image (default 60, 0 = none)" << std::endl; } From 31759791df27237df3db059441bd602fc72b5b73 Mon Sep 17 00:00:00 2001 From: Filip Leonarski Date: Wed, 18 Nov 2026 14:33:52 +0100 Subject: [PATCH 19/41] FPGAImagePuller: no lock-order inversion between images_mutex and order_mutex; cancel ends a blocking wait The hang of a non-blocking run on four cards (backtrace from the server): a module thread dropping an image called Emit from GetSlot with images_mutex held and waited for order_mutex, while a compress thread in Emit, holding order_mutex, destroyed the last copy of an image - the receiver had already taken and dropped the copy just queued - and its deleter (ReturnSlot) waited for images_mutex. Only a dropping run goes through that branch of GetSlot. - GetSlot emits a dropped image after releasing images_mutex. - Emit and the flush at the end keep the copies of what they let out until order_mutex is released, so no slot goes back under it. - Cancel() sets `cancelled`: an image waiting for a slot in blocking mode is dropped instead, as after a cancel nobody may take the images holding the slots (FPGAImagePuller_Blocking_CancelWithoutConsumer hung before, passes now). - FPGAImagePuller_DroppingNoLockInversion: 4 modules, 2 slots, 8 compress threads, a consumer that pauses so that images are dropped and frees them at once; under a time limit. The race window is a few instructions wide: on the mock it did not hang before the fix either, so it guards the lock order rather than reproducing the server's hang. - jfjoch_fpga_stills_test -v: the receiver's and the stills analysis' counts and whether each card is done, beside the cards' progress, so that a run that stops shows which part waits. The 4 h hang of a blocking two-card mock run (2026-11-18 09:29) was the binary before 4c8af0dbc (late frames of a lagging card not released while a module waited); the same run now takes 17-45 s (4 repeats). Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01UqXYdHHZ4cogS1mrGUtfN7 --- receiver/FPGAImagePuller.cpp | 74 ++++++++++++++++++------------- receiver/FPGAImagePuller.h | 1 + tests/FPGAImagePullerTest.cpp | 62 ++++++++++++++++++++++++++ tools/jfjoch_fpga_stills_test.cpp | 13 +++++- 4 files changed, 118 insertions(+), 32 deletions(-) diff --git a/receiver/FPGAImagePuller.cpp b/receiver/FPGAImagePuller.cpp index 5d0d884a4..b23af6da5 100644 --- a/receiver/FPGAImagePuller.cpp +++ b/receiver/FPGAImagePuller.cpp @@ -90,6 +90,9 @@ void FPGAImagePuller::SetError(std::exception_ptr e) { } void FPGAImagePuller::Cancel() { + // An image waiting for a slot is dropped from here on: after a cancel nobody may take the images that hold them + cancelled = true; + slot_returned.notify_all(); for (int d = 0; d < experiment.GetDataStreamsNum(); d++) devices[d].Cancel(); } @@ -163,34 +166,40 @@ int64_t FPGAImagePuller::LastFrame() const { } std::shared_ptr FPGAImagePuller::GetSlot(int64_t image_number) { - std::unique_lock ul(images_mutex); - std::shared_ptr slot; - while (!slot) { - if (image_dropped[image_number]) - return nullptr; - // Another module may have started the image while this one waited - if (const auto it = images_in_progress.find(image_number); it != images_in_progress.end()) - return it->second; - if (!free_slots.empty()) { - slot = free_slots.back(); - free_slots.pop_back(); - } else if (blocking && !failed) { - const auto t0 = std::chrono::steady_clock::now(); - slot_returned.wait_for(ul, std::chrono::milliseconds(10)); - slot_wait_ns += std::chrono::duration_cast( - std::chrono::steady_clock::now() - t0).count(); - } else { - image_dropped[image_number] = 1; - dropped_images++; - Emit(image_number, std::nullopt); - return nullptr; + { + std::unique_lock ul(images_mutex); + std::shared_ptr slot; + while (!slot) { + if (image_dropped[image_number]) + return nullptr; + // Another module may have started the image while this one waited + if (const auto it = images_in_progress.find(image_number); it != images_in_progress.end()) + return it->second; + if (!free_slots.empty()) { + slot = free_slots.back(); + free_slots.pop_back(); + } else if (blocking && !failed && !cancelled) { + const auto t0 = std::chrono::steady_clock::now(); + slot_returned.wait_for(ul, std::chrono::milliseconds(10)); + slot_wait_ns += std::chrono::duration_cast( + std::chrono::steady_clock::now() - t0).count(); + } else { + image_dropped[image_number] = 1; + dropped_images++; + break; + } + } + if (slot) { + slot->image_number = image_number; + slot->metadata = std::make_unique(experiment); + slot->modules_left = static_cast(experiment.GetModulesNum()); + images_in_progress[image_number] = slot; + return slot; } } - slot->image_number = image_number; - slot->metadata = std::make_unique(experiment); - slot->modules_left = static_cast(experiment.GetModulesNum()); - images_in_progress[image_number] = slot; - return slot; + // Not under images_mutex: Emit takes order_mutex, and a slot going back from under order_mutex takes images_mutex + Emit(image_number, std::nullopt); + return nullptr; } void FPGAImagePuller::ReturnSlot(const std::shared_ptr &slot) { @@ -291,13 +300,17 @@ void FPGAImagePuller::CompressThread() { // Whichever thread finishes the image next in line lets it, and those waiting behind it, out. void FPGAImagePuller::Emit(int64_t image_number, std::optional output) { + // The copies of the images let out here go only once order_mutex is released (the lock is declared after them, and + // `output` outlives both): the last copy of an image returns its slot, under images_mutex + std::vector released; std::unique_lock ul(order_mutex); - images_done.emplace(image_number, std::move(output)); + images_done.try_emplace(image_number, output); for (auto it = images_done.begin(); (it != images_done.end()) && (it->first == next_image); it = images_done.erase(it), next_image++) { if (it->second) { it->second->received = std::chrono::steady_clock::now(); - outside_fifo.Put(std::move(*it->second)); + outside_fifo.Put(*it->second); + released.push_back(std::move(*it->second)); } } } @@ -316,11 +329,12 @@ void FPGAImagePuller::FinalizeMeasurement() { // Only an error leaves images unfinished, holding back those behind them { + std::map> left; // destroyed after order_mutex, as in Emit std::unique_lock ul(order_mutex); for (auto &[n, output]: images_done) if (output) - outside_fifo.Put(std::move(*output)); - images_done.clear(); + outside_fifo.Put(*output); + left.swap(images_done); } if (dropped_images > 0) diff --git a/receiver/FPGAImagePuller.h b/receiver/FPGAImagePuller.h index d5d90a16e..599abfce7 100644 --- a/receiver/FPGAImagePuller.h +++ b/receiver/FPGAImagePuller.h @@ -69,6 +69,7 @@ private: std::mutex error_mutex; std::exception_ptr error; std::atomic failed = false; // a failed card may never report finished: nothing waits for it then + std::atomic cancelled = false; // Cancel(): no image waits for a slot any more void SetError(std::exception_ptr e); std::vector> acquire_futures; diff --git a/tests/FPGAImagePullerTest.cpp b/tests/FPGAImagePullerTest.cpp index 9cc618646..178248b91 100644 --- a/tests/FPGAImagePullerTest.cpp +++ b/tests/FPGAImagePullerTest.cpp @@ -7,6 +7,7 @@ #include #include +#include #include #include #include @@ -500,6 +501,67 @@ TEST_CASE("FPGAImagePuller_SlowConsumer_Blocking", "[FPGAImagePuller]") { CHECK(numbers[i] == static_cast(i)); } +// Blocking, and nobody takes the images: a cancel must still end the puller (the images waiting for a slot are +// dropped). Run on a thread of its own, so that a hang fails the test instead of stopping the run. +TEST_CASE("FPGAImagePuller_Blocking_CancelWithoutConsumer", "[FPGAImagePuller]") { + auto x = Base(DetJF(1), 20, 1); + x.Conversion(); + x.Compression(CompressionAlgorithm::BSHUF_LZ4); + + auto devices = std::make_shared(Devices(x)); + auto logger = std::make_shared("FPGAImagePuller_Blocking_Cancel"); + auto mask = std::make_shared(x); + auto puller = std::make_shared(x, *mask, nullptr, *devices, *logger, 2, 2, true); + std::this_thread::sleep_for(1s); + + auto stopped = std::make_shared>(); + auto done = stopped->get_future(); + std::thread([puller, devices, logger, mask, stopped] { + puller->Cancel(); + try { + puller->Stop(); + } catch (...) {} + stopped->set_value(); + }).detach(); + REQUIRE(done.wait_for(30s) == std::future_status::ready); + CHECK(puller->GetDroppedImages() > 0); +} + +// Not blocking, with drops: a module thread drops an image (GetSlot, images_mutex) while a compress thread lets an +// image out (Emit, order_mutex) and the consumer frees images at once, so a slot can go back from inside Emit. The +// two locks must never be held the other way round. Run on a thread of its own, so that a hang fails the test. +TEST_CASE("FPGAImagePuller_DroppingNoLockInversion", "[FPGAImagePuller]") { + auto x = Base(DetJF(4), 3000, 1); + x.Conversion(); + x.Compression(CompressionAlgorithm::NO_COMPRESSION); + + auto devices = std::make_shared(Devices(x)); + auto logger = std::make_shared("FPGAImagePuller_DroppingNoLockInversion"); + auto mask = std::make_shared(x); + auto finished = std::make_shared>(); + auto done = finished->get_future(); + std::thread([x, devices, logger, mask, finished] { + FPGAImagePuller puller(x, *mask, nullptr, *devices, *logger, 8, 2); + size_t images = 0; + bool end = false; + while (!end) { + // Now and then the consumer pauses, so that the slots run out and images are dropped + if (images % 7 == 0) + std::this_thread::sleep_for(1ms); + const auto m = puller.PollImage(10ms); + if (m && m->cbor->data_message) + images++; + end = m && m->cbor->end_message.has_value(); + } + puller.Stop(); + std::cout << "dropping, no lock inversion: " << images << " images, " << puller.GetDroppedImages() + << " dropped" << std::endl; + finished->set_value(images + puller.GetDroppedImages()); + }).detach(); + REQUIRE(done.wait_for(120s) == std::future_status::ready); + CHECK(done.get() <= 3000); +} + // Paced: the images are taken from the card at most at the rate given TEST_CASE("FPGAImagePuller_Paced", "[FPGAImagePuller]") { auto x = Base(DetJF(1), 10, 1); diff --git a/tools/jfjoch_fpga_stills_test.cpp b/tools/jfjoch_fpga_stills_test.cpp index a7359dcf7..76e654b4b 100644 --- a/tools/jfjoch_fpga_stills_test.cpp +++ b/tools/jfjoch_fpga_stills_test.cpp @@ -189,8 +189,17 @@ bool RunDataset(Logger &logger, AcquisitionDeviceGroup &aq_devices, const std::s std::this_thread::sleep_for(std::chrono::milliseconds(500)); std::string line; for (int i = 0; i < x.GetDataStreamsNum(); i++) - line += fmt::format(" card {}: {} .. {}", i, aq_devices[i].Counters().GetSlowestFrameNumber(), - aq_devices[i].Counters().GetFastestFrameNumber()); + line += fmt::format(" card {}: {} .. {}{}", i, aq_devices[i].Counters().GetSlowestFrameNumber(), + aq_devices[i].Counters().GetFastestFrameNumber(), + aq_devices[i].Counters().IsAcquisitionFinished() ? " done" : ""); + // Where a run stands, so that one that stops shows which part waits + if (const auto st = service.GetStatus()) + line += fmt::format(" receiver: collected {} sent {} dropped {}", st->images_collected, + st->images_sent, st->images_dropped); + const auto live = service.GetRugnuxStatus(); + if (live.stills) + line += fmt::format(" stills: held {} analysed {} pre-pass {}", live.stills->images_held, + live.stills->images_analysed, static_cast(live.stills->prepass)); logger.Debug("{:.1f} s{}", std::chrono::duration(std::chrono::steady_clock::now() - wall_start).count(), line); } From 11cad9f40fcb1352424c6cde9c3083c6c44cbfbd Mon Sep 17 00:00:00 2001 From: Filip Leonarski Date: Wed, 18 Nov 2026 14:56:43 +0100 Subject: [PATCH 20/41] jfjoch_fpga_stills_test: -r refused with -d; the slots a free-running card drift needs -r holds frame i on the host until i/rate, which makes the card wait for its buffers: with -d that is blocking again, not a detector at that rate. Dropping the frames that come early instead is no better: the cards' generators run free, each at its own speed, so each card would keep a different subset of the frames. The combination is refused. With -d, the drops "no free slot" come from those free-running generators drifting apart: the images the cards ahead have started hold the puller's slots until the frames of the card behind arrive (it is waited for until max_slots behind). The receiver is not what holds them: JFJochReceiverRugnuxStills copies the image into its image buffer (or its own copy) in OnImage and the puller's output, with the slot, goes when OnImage returns. A detector's modules share a trigger and do not drift. Usage and docs say to give -p at least the drift -v shows (mock, 9M, 4 cards, 1500 images: efficiency 0.49 with 128 slots, 0.98 with 512). Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01UqXYdHHZ4cogS1mrGUtfN7 --- docs/TOOLS.md | 8 +++++++- tools/jfjoch_fpga_stills_test.cpp | 14 ++++++++++++-- 2 files changed, 19 insertions(+), 3 deletions(-) diff --git a/docs/TOOLS.md b/docs/TOOLS.md index c410dd341..5517771d1 100644 --- a/docs/TOOLS.md +++ b/docs/TOOLS.md @@ -106,7 +106,13 @@ jfjoch_fpga_stills_test [-i ] [-s ] [-N ] [-B ] [-C before the network stack; a real detector's UDP packets would be lost at that point instead). The firmware cannot pace the generator (it has no frame period): `-r` paces it from the host, the puller taking image *i* from the cards no earlier than *i / rate* after the start, so the card waits for the - host either way. One collection is run per rate of `-r` (default `0`, as fast as it goes). + host either way. One collection is run per rate of `-r` (default `0`, as fast as it goes). `-r` is refused + with `-d`: holding a frame on the host makes the card wait, which is blocking again, and dropping the frames + that come early would keep a different subset on each card, as their generators run apart. +- With `-d` the cards' generators run free, each at its own speed, so the cards drift apart - unlike the + modules of a detector, which a common trigger keeps together. The images started by the cards ahead hold + the puller's slots until the frames of the card behind arrive: give `-p` at least the frames the cards + drift apart (`-v` shows each card's frames), or images are dropped for want of a slot. - For each rate it reports the rate images were delivered (first to last image), the fraction of that time the source was blocked by the chain behind it (the time the puller's module threads waited for a free slot, mean over the modules), the sustained rate (images / wall time, start to the end of the analysis) diff --git a/tools/jfjoch_fpga_stills_test.cpp b/tools/jfjoch_fpga_stills_test.cpp index 76e654b4b..992ecc338 100644 --- a/tools/jfjoch_fpga_stills_test.cpp +++ b/tools/jfjoch_fpga_stills_test.cpp @@ -7,6 +7,7 @@ // The generator cycles through the images its memory holds, so images repeat: throughput, latency and indexing rate // are meaningful, the merge and its statistics are not. +#include #include #include #include @@ -39,10 +40,13 @@ void print_usage(Logger &logger) { logger.Info(" -S Space group of the collection (a space group stored in the file is ignored)"); logger.Info(" -X Indexing (auto|fft|fftw|ffbidx), auto is default"); logger.Info(" -t Indexing thread pool size (default: 4)"); - logger.Info(" -r Rates the source is paced at, one collection each (default: 0 = as fast as it goes)"); + logger.Info(" -r Rates the source is paced at, one collection each (default: 0 = as fast as it goes); the"); + logger.Info(" host takes frame i no earlier than i/rate, the card waits meanwhile: blocking runs only"); logger.Info(" -p FPGAImagePuller slots (default 128)"); logger.Info(" -k Analyse 1 of every images on average (rugnux live stills_downsample, default 1)"); - logger.Info(" -d Not blocking, as the broker runs: images the host has no room for are dropped"); + logger.Info(" -d Not blocking, as the broker runs: images the host has no room for are dropped. The cards'"); + logger.Info(" generators run free and apart (each at its own speed), unlike a detector's modules:"); + logger.Info(" give -p at least the frames they drift apart (-v shows them)"); logger.Info(" -K{} Mock of the card instead of /dev/jfjoch* (optional: its generator memory, default 64 MiB ="); logger.Info(" 128 module frames)"); } @@ -387,6 +391,12 @@ int main(int argc, char **argv) { print_usage(logger); exit(EXIT_FAILURE); } + // The generator has no frame period: -r holds frames on the host, which makes the card wait - blocking again. + // Dropping the frames that come early instead would keep a different subset on each card, as they run apart. + if (dropping && std::any_of(rates.begin(), rates.end(), [](double r) { return r > 0; })) { + logger.Error("-r paces the source through the card waiting for the host, so it cannot be used with -d"); + exit(EXIT_FAILURE); + } logger.Verbose(verbose); From 0060c734b49e2c8fc8775f048c43dbd8065ed7ea Mon Sep 17 00:00:00 2001 From: Filip Leonarski Date: Wed, 18 Nov 2026 15:14:58 +0100 Subject: [PATCH 21/41] FPGAImagePuller: a slot goes back once its image is compressed; dummy modules for even cards - The compressed image is copied into a buffer of the output's own and the slot returned at once: slots are held while an image is assembled and compressed, not while it waits in the queue or in the receiver. The queue keeps its bound of max_slots images: not blocking, an image that finds it full is dropped and counted; blocking, it waits for room while the receiver takes images (until Cancel()). The end message waits the same way. Cancel() (the receiver stops taking images) is now apart from stopping the cards (CancelCards), which the puller does at its own end without giving up on the receiver. No slot deleter runs under a lock any more. - modules_per_card (FPGAImagePullerSettings): the cards run FPGAImagePuller::CardExperiment, each card with that many modules - its modules of the image first, then dummies the puller only returns to the card. The internal generator runs as fast as its card's modules allow, so a 9M on 4 cards (5, 5, 4, 4) ran at 2.04 and 2.55 kHz on the server and drifted ~500 images/s apart; padded to 5 each the cards send the same bytes. The expected packets, the efficiency and the image are of the image's modules. - jfjoch_fpga_stills_test pads by default where the modules do not divide evenly (-U: not), lists each card's modules and dummies, and loads the generator card by card with zeros for the dummies; the distinct images follow the padded count. Mock, 9M, 4 cards, blocking, 3000 images: padded and -U give the same images (indexing 0.760, 48.7 spots per image, 25 distinct). The mock cards' speed does not go with their modules (each is two CPU threads), so on the mock padding does not keep them in step: that is for the server to show (-v). Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01UqXYdHHZ4cogS1mrGUtfN7 --- docs/TOOLS.md | 12 ++-- receiver/FPGAImagePuller.cpp | 94 +++++++++++++++++++++--------- receiver/FPGAImagePuller.h | 13 ++++- receiver/JFJochReceiverService.cpp | 6 +- receiver/JFJochReceiverService.h | 8 ++- tools/jfjoch_fpga_stills_test.cpp | 51 +++++++++++----- 6 files changed, 131 insertions(+), 53 deletions(-) diff --git a/docs/TOOLS.md b/docs/TOOLS.md index 5517771d1..bfb11fd86 100644 --- a/docs/TOOLS.md +++ b/docs/TOOLS.md @@ -109,10 +109,14 @@ jfjoch_fpga_stills_test [-i ] [-s ] [-N ] [-B ] [-C host either way. One collection is run per rate of `-r` (default `0`, as fast as it goes). `-r` is refused with `-d`: holding a frame on the host makes the card wait, which is blocking again, and dropping the frames that come early would keep a different subset on each card, as their generators run apart. -- With `-d` the cards' generators run free, each at its own speed, so the cards drift apart - unlike the - modules of a detector, which a common trigger keeps together. The images started by the cards ahead hold - the puller's slots until the frames of the card behind arrive: give `-p` at least the frames the cards - drift apart (`-v` shows each card's frames), or images are dropped for want of a slot. +- The cards' generators run free, each as fast as its modules' bandwidth allows, so cards with different + numbers of modules (a 9M on 4 cards: 5, 5, 4, 4) drift apart - unlike the modules of a detector, which a + common trigger keeps together - and with `-d` the images started by the cards ahead hold the puller's slots + until the frames of the card behind arrive. Where the modules do not divide evenly, every card is therefore + given as many modules as the largest, the rest dummy modules (zeros) the generator sends and the puller does + not read (`FPGAImagePuller::CardExperiment`; not part of the image, nor of its efficiency); `-U` leaves them + out. The start lines give each card's modules and dummies; the distinct images follow the padded count. With + `-U` (or cards that still drift, `-v` shows each card's frames) give `-p` at least the frames they drift apart. - For each rate it reports the rate images were delivered (first to last image), the fraction of that time the source was blocked by the chain behind it (the time the puller's module threads waited for a free slot, mean over the modules), the sustained rate (images / wall time, start to the end of the analysis) diff --git a/receiver/FPGAImagePuller.cpp b/receiver/FPGAImagePuller.cpp index b23af6da5..c017651f1 100644 --- a/receiver/FPGAImagePuller.cpp +++ b/receiver/FPGAImagePuller.cpp @@ -10,9 +10,10 @@ FPGAImagePuller::FPGAImagePuller(const DiffractionExperiment &in_experiment, const PixelMask &mask, const JFCalibration *calibration, AcquisitionDeviceGroup &in_devices, Logger &in_logger, int64_t compression_threads, size_t in_max_slots, - bool in_blocking, double in_frame_rate_hz) - : ImagePuller(in_max_slots + 2), // every slot, the start and the end message: Put never finds it full + bool in_blocking, double in_frame_rate_hz, int64_t modules_per_card) + : ImagePuller(in_max_slots + 2), // as many images as slots, the start and the end message experiment(in_experiment), + card_experiment(CardExperiment(in_experiment, modules_per_card)), logger(in_logger), devices(in_devices), max_slots(in_max_slots), @@ -28,11 +29,14 @@ FPGAImagePuller::FPGAImagePuller(const DiffractionExperiment &in_experiment, con adu_histogram.emplace_back(std::make_unique()); for (int d = 0; d < ndatastreams; d++) { - devices[d].PrepareAction(experiment); - expected_packets_per_image += devices[d].Counters().GetExpectedPacketsPerImage(); + devices[d].PrepareAction(card_experiment); + // Of the modules of the image, not the dummies + expected_packets_per_image += devices[d].Counters().GetExpectedPacketsPerImage() + * experiment.GetModulesNum(d) / card_experiment.GetModulesNum(d); } - if (experiment.GetDetectorType() != DetectorType::JUNGFRAU) + // The calibration and the mask are of the modules of the image + if ((experiment.GetDetectorType() != DetectorType::JUNGFRAU) || (modules_per_card > 0)) calibration = nullptr; // Making a slot is slow and its buffers are written once here: none is made, nor first touched, during the run @@ -50,7 +54,7 @@ FPGAImagePuller::FPGAImagePuller(const DiffractionExperiment &in_experiment, con compress_futures.emplace_back(std::async(std::launch::async, &FPGAImagePuller::CompressThread, this)); for (int d = 0; d < ndatastreams; d++) - for (int m = 0; m < experiment.GetModulesNum(d); m++) + for (int m = 0; m < card_experiment.GetModulesNum(d); m++) module_futures.emplace_back(std::async(std::launch::async, &FPGAImagePuller::ModuleThread, this, d, m)); std::latch ready(ndatastreams); @@ -82,6 +86,16 @@ FPGAImagePuller::~FPGAImagePuller() { outside_fifo.Clear(); } +DiffractionExperiment FPGAImagePuller::CardExperiment(const DiffractionExperiment &x, int64_t modules_per_card) { + if (modules_per_card <= 0) + return x; + DiffractionExperiment ret(x); + const DetectorSettings settings = x.GetDetectorSettings(); + ret.Detector(DetJF(static_cast(modules_per_card * x.GetDataStreamsNum()))); + ret.ImportDetectorSettings(settings); + return ret; +} + void FPGAImagePuller::SetError(std::exception_ptr e) { std::unique_lock ul(error_mutex); if (!error) @@ -90,9 +104,14 @@ void FPGAImagePuller::SetError(std::exception_ptr e) { } void FPGAImagePuller::Cancel() { - // An image waiting for a slot is dropped from here on: after a cancel nobody may take the images that hold them + // An image waiting for a slot or for room in the queue is dropped from here on: after a cancel the receiver takes + // no more images cancelled = true; slot_returned.notify_all(); + CancelCards(); +} + +void FPGAImagePuller::CancelCards() { for (int d = 0; d < experiment.GetDataStreamsNum(); d++) devices[d].Cancel(); } @@ -112,11 +131,14 @@ void FPGAImagePuller::AcquireThread(uint16_t data_stream, const PixelMask &mask, // Only what the card needs for the pixels: its analysis results are not read. if (calibration != nullptr) device.InitializeCalibration(experiment, *calibration); - device.InitializePixelMask(experiment, mask); - device.StartAction(experiment); + if (card_experiment.GetModulesNum() == experiment.GetModulesNum()) + device.InitializePixelMask(experiment, mask); + else + device.InitializeEmptyPixelMask(card_experiment); + device.StartAction(card_experiment); } catch (...) { SetError(std::current_exception()); - Cancel(); // the module threads of the other cards have to come out as well + CancelCards(); // the module threads of the other cards have to come out as well ready.count_down(); return; } @@ -126,7 +148,7 @@ void FPGAImagePuller::AcquireThread(uint16_t data_stream, const PixelMask &mask, device.WaitForActionComplete(); } catch (...) { SetError(std::current_exception()); - Cancel(); + CancelCards(); } } @@ -232,7 +254,9 @@ void FPGAImagePuller::ModuleThread(uint16_t data_stream, uint16_t module_number) break; const bool collected = counters.IsAnyPacketCollected(image, module_number); - if (const auto slot = GetSlot(image)) { + // A dummy module (CardExperiment): its frames only go back to the card + const bool dummy = module_number >= experiment.GetModulesNum(data_stream); + if (const auto slot = dummy ? nullptr : GetSlot(image)) { if (collected) { const DeviceOutput *output = device.GetDeviceOutput(image, module_number); slot->metadata->Process(output); @@ -254,7 +278,7 @@ void FPGAImagePuller::ModuleThread(uint16_t data_stream, uint16_t module_number) } } catch (...) { SetError(std::current_exception()); - Cancel(); + CancelCards(); } } @@ -276,22 +300,23 @@ void FPGAImagePuller::CompressThread() { continue; } - message.image = slot->transformation.GetCompressedImage(); + // The compressed image goes to a buffer of the output's own, and the slot back at once: the slots are + // held only while an image is assembled and compressed, not while it waits for the receiver + const CompressedImage compressed = slot->transformation.GetCompressedImage(); + auto bytes = std::make_shared>(compressed.GetCompressed(), + compressed.GetCompressed() + compressed.GetCompressedSize()); + ReturnSlot(slot); + message.image = CompressedImage(bytes->data(), bytes->size(), compressed.GetWidth(), compressed.GetHeight(), + compressed.GetMode(), compressed.GetCompressionAlgorithm()); ImagePullerOutput output; output.cbor = std::make_shared(message); - // The image lives in the slot: it goes back when the last copy of this output is gone. - output.raw = std::shared_ptr( - new ReceiveBufferRegion{const_cast(message.image.GetCompressed()), - message.image.GetCompressedSize()}, - [this, slot](ReceiveBufferRegion *region) { - delete region; - ReturnSlot(slot); - }); + output.raw = std::shared_ptr(new ReceiveBufferRegion{bytes->data(), bytes->size()}, + [bytes](ReceiveBufferRegion *region) { delete region; }); Emit(image_number, std::move(output)); } catch (...) { SetError(std::current_exception()); - Cancel(); + CancelCards(); ReturnSlot(slot); Emit(image_number, std::nullopt); } @@ -309,7 +334,10 @@ void FPGAImagePuller::Emit(int64_t image_number, std::optionalsecond) { it->second->received = std::chrono::steady_clock::now(); - outside_fifo.Put(*it->second); + // The queue holds as many images as there are slots: blocking, the image waits for room; not + // blocking, it is dropped + if (!(blocking ? PutWhileNotCancelled(*it->second) : outside_fifo.Put(*it->second))) + dropped_images++; released.push_back(std::move(*it->second)); } } @@ -323,7 +351,7 @@ void FPGAImagePuller::FinalizeMeasurement() { for (auto &f: compress_futures) f.get(); - Cancel(); + CancelCards(); for (auto &f: acquire_futures) f.get(); @@ -332,8 +360,8 @@ void FPGAImagePuller::FinalizeMeasurement() { std::map> left; // destroyed after order_mutex, as in Emit std::unique_lock ul(order_mutex); for (auto &[n, output]: images_done) - if (output) - outside_fifo.Put(*output); + if (output && !PutWhileNotCancelled(*output)) + dropped_images++; left.swap(images_done); } @@ -343,6 +371,14 @@ void FPGAImagePuller::FinalizeMeasurement() { EndMessage end{}; for (size_t i = 0; i < adu_histogram.size(); i++) end.adu_histogram["module" + std::to_string(i)] = adu_histogram[i]->GetHistogram(); - outside_fifo.Put({.cbor = std::make_shared(end), - .received = std::chrono::steady_clock::now()}); + PutWhileNotCancelled({.cbor = std::make_shared(end), + .received = std::chrono::steady_clock::now()}); +} + +// Waits for room in the queue, as long as the receiver takes from it: after a cancel it no longer does +bool FPGAImagePuller::PutWhileNotCancelled(const ImagePullerOutput &output) { + while (!outside_fifo.PutTimeout(output, std::chrono::milliseconds(100))) + if (cancelled) + return false; + return true; } diff --git a/receiver/FPGAImagePuller.h b/receiver/FPGAImagePuller.h index 599abfce7..f34d862f2 100644 --- a/receiver/FPGAImagePuller.h +++ b/receiver/FPGAImagePuller.h @@ -40,6 +40,8 @@ private: }; const DiffractionExperiment experiment; + // What the cards run: the experiment, or with dummy modules (CardExperiment) + const DiffractionExperiment card_experiment; Logger &logger; AcquisitionDeviceGroup &devices; const size_t max_slots; @@ -89,11 +91,20 @@ private: std::shared_ptr GetSlot(int64_t image_number); void ReturnSlot(const std::shared_ptr &slot); void Emit(int64_t image_number, std::optional output); + bool PutWhileNotCancelled(const ImagePullerOutput &output); + void CancelCards(); public: // Arms the cards; when it returns the detector can be started. FPGAImagePuller(const DiffractionExperiment &experiment, const PixelMask &mask, const JFCalibration *calibration, AcquisitionDeviceGroup &devices, Logger &logger, int64_t compression_threads, - size_t max_slots = DefaultSlots, bool blocking = false, double frame_rate_hz = 0); + size_t max_slots = DefaultSlots, bool blocking = false, double frame_rate_hz = 0, + int64_t modules_per_card = 0); + + // The experiment the cards run where each carries modules_per_card modules (0: as `x` splits them): each card's + // modules of `x` first, in their order, then dummy modules the generator sends and the puller does not read. + // For the internal generator, whose speed goes with the modules of the card: cards of different module counts + // run apart, where a detector's modules keep in step. + static DiffractionExperiment CardExperiment(const DiffractionExperiment &x, int64_t modules_per_card); ~FPGAImagePuller() override; void Disconnect() override {} diff --git a/receiver/JFJochReceiverService.cpp b/receiver/JFJochReceiverService.cpp index 07114d667..988171da7 100644 --- a/receiver/JFJochReceiverService.cpp +++ b/receiver/JFJochReceiverService.cpp @@ -41,7 +41,7 @@ JFJochReceiverService &JFJochReceiverService::RugnuxLive(bool enable, std::share } JFJochReceiverService &JFJochReceiverService::FPGAImagePullerSettings(size_t slots, bool blocking, double frame_rate_hz, - bool always) { + bool always, int64_t modules_per_card) { std::unique_lock ul_state(state_mutex); if (state != ReceiverState::Idle) throw JFJochException(JFJochExceptionCategory::WrongDAQState, @@ -50,6 +50,7 @@ JFJochReceiverService &JFJochReceiverService::FPGAImagePullerSettings(size_t slo fpga_image_puller_blocking = blocking; fpga_image_puller_rate_hz = frame_rate_hz; fpga_image_puller_always = always; + fpga_image_puller_modules_per_card = modules_per_card; return *this; } @@ -146,7 +147,8 @@ void JFJochReceiverService::Start(const DiffractionExperiment &experiment, if (FPGAImagePullerFor(experiment)) { fpga_puller = std::make_shared(experiment, pixel_mask, calibration, aq_devices, logger, nthreads, fpga_image_puller_slots, - fpga_image_puller_blocking, fpga_image_puller_rate_hz); + fpga_image_puller_blocking, fpga_image_puller_rate_hz, + fpga_image_puller_modules_per_card); puller = fpga_puller; } diff --git a/receiver/JFJochReceiverService.h b/receiver/JFJochReceiverService.h index acc361c23..3ac3cbed2 100644 --- a/receiver/JFJochReceiverService.h +++ b/receiver/JFJochReceiverService.h @@ -43,6 +43,7 @@ class JFJochReceiverService { // A PSI collection analysed by rugnux live goes through FPGAImagePuller to the stream receivers bool fpga_image_puller_always = false; + int64_t fpga_image_puller_modules_per_card = 0; size_t fpga_image_puller_slots = FPGAImagePuller::DefaultSlots; bool fpga_image_puller_blocking = false; double fpga_image_puller_rate_hz = 0; @@ -76,11 +77,12 @@ public: int64_t stills_downsample = 1); RugnuxLiveSnapshot GetRugnuxStatus() const; void ClearRugnuxStatus(); // back to Idle, as before any collection - // slots, blocking, frame_rate_hz: see FPGAImagePuller. always: every PSI collection but pedestal and host - // summation through the puller, without rugnux to JFJochReceiverLite (for tests comparing it with + // slots, blocking, frame_rate_hz, modules_per_card: see FPGAImagePuller. always: every PSI collection but pedestal + // and host summation through the puller, without rugnux to JFJochReceiverLite (for tests comparing it with // JFJochReceiverFPGA) JFJochReceiverService& FPGAImagePullerSettings(size_t slots = FPGAImagePuller::DefaultSlots, bool blocking = false, - double frame_rate_hz = 0, bool always = false); + double frame_rate_hz = 0, bool always = false, + int64_t modules_per_card = 0); // Of the last collection through FPGAImagePuller: FPGAImagePuller::GetSlotWaitTime_s, 0 without one double GetFPGAImagePullerSlotWaitTime_s() const; JFJochReceiverService& PreviewSocket(const std::string &addr, const std::optional &watermark = {}); diff --git a/tools/jfjoch_fpga_stills_test.cpp b/tools/jfjoch_fpga_stills_test.cpp index 992ecc338..eb6254a77 100644 --- a/tools/jfjoch_fpga_stills_test.cpp +++ b/tools/jfjoch_fpga_stills_test.cpp @@ -43,10 +43,11 @@ void print_usage(Logger &logger) { logger.Info(" -r Rates the source is paced at, one collection each (default: 0 = as fast as it goes); the"); logger.Info(" host takes frame i no earlier than i/rate, the card waits meanwhile: blocking runs only"); logger.Info(" -p FPGAImagePuller slots (default 128)"); + logger.Info(" -U No dummy modules: where the cards carry different numbers of modules, they run apart"); logger.Info(" -k Analyse 1 of every images on average (rugnux live stills_downsample, default 1)"); logger.Info(" -d Not blocking, as the broker runs: images the host has no room for are dropped. The cards'"); - logger.Info(" generators run free and apart (each at its own speed), unlike a detector's modules:"); - logger.Info(" give -p at least the frames they drift apart (-v shows them)"); + logger.Info(" generators run free, each at a speed that goes with its modules: where the modules do not"); + logger.Info(" divide evenly, each card is given dummy modules up to the largest count (-U: not)"); logger.Info(" -K{} Mock of the card instead of /dev/jfjoch* (optional: its generator memory, default 64 MiB ="); logger.Info(" 128 module frames)"); } @@ -92,7 +93,7 @@ int64_t GeneratorImages(AcquisitionDeviceGroup &aq_devices, const DiffractionExp bool RunDataset(Logger &logger, AcquisitionDeviceGroup &aq_devices, const std::string &file, std::optional nimages, uint16_t nstreams, uint16_t nthreads, size_t send_buffer_size_MiB, const IndexingSettings &indexing, const std::optional &cell, size_t puller_slots, - const std::vector &rates, bool dropping, int64_t downsample, + const std::vector &rates, bool dropping, bool pad, int64_t downsample, const std::optional &space_group) { RegisterHDF5Filter(); JFJochHDF5Reader reader; @@ -127,12 +128,18 @@ bool RunDataset(Logger &logger, AcquisitionDeviceGroup &aq_devices, const std::s file_x.GetGemmiSpaceGroup()->hm); x.ImportIndexingSettings(indexing); - const int64_t generator_images = GeneratorImages(aq_devices, x, reader.GetNumberOfImages()); + // The generator's speed goes with the modules of its card: with the modules not dividing evenly, every card is + // given as many as the largest, the rest dummies the puller does not read (FPGAImagePuller::CardExperiment) + const int64_t modules_per_card = (pad && (x.GetModulesNum() % nstreams != 0)) ? x.GetModulesNum(0) : 0; + DiffractionExperiment card_x = FPGAImagePuller::CardExperiment(x, modules_per_card); + + const int64_t generator_images = GeneratorImages(aq_devices, card_x, reader.GetNumberOfImages()); if (generator_images < 1) { - logger.Error("The card memory cannot hold one image of {} modules", x.GetModulesNum()); + logger.Error("The card memory cannot hold one image of {} modules", card_x.GetModulesNum(0)); return false; } x.InternalPacketGeneratorImages(generator_images, FPGA_INTERNAL_GENERATOR_MAX_IMAGES); + card_x.InternalPacketGeneratorImages(generator_images, FPGA_INTERNAL_GENERATOR_MAX_IMAGES); PixelMask mask(x); if (dataset->pixel_mask->GetMask().size() == x.GetPixelsNum()) @@ -141,9 +148,17 @@ bool RunDataset(Logger &logger, AcquisitionDeviceGroup &aq_devices, const std::s logger.Info("Dataset {}: {} images of {} modules, {} distinct ones in the generator, {} in the run", file, reader.GetNumberOfImages(), x.GetModulesNum(), generator_images, x.GetImageNum()); for (int i = 0; i < x.GetDataStreamsNum(); i++) - logger.Info(" card {}: modules {}-{}, generator memory {} module frames, {} used", i, + logger.Info(" card {}: modules {}-{} and {} dummy, generator memory {} module frames, {} used", i, x.GetFirstModuleOfDataStream(i), x.GetFirstModuleOfDataStream(i) + x.GetModulesNum(i) - 1, - aq_devices[i].GetInternalGeneratorModuleFrames(), x.GetModulesNum(i) * generator_images); + card_x.GetModulesNum(i) - x.GetModulesNum(i), aq_devices[i].GetInternalGeneratorModuleFrames(), + card_x.GetModulesNum(i) * generator_images); + if (dropping && !pad) { + for (int i = 1; i < x.GetDataStreamsNum(); i++) + if (x.GetModulesNum(i) != x.GetModulesNum(0)) { + logger.Warning("The cards carry different numbers of modules: their generators run apart (-U)"); + break; + } + } for (int m = 0; m < x.GetModulesNum(); m++) logger.Debug(" module {}: pixel 0 at ({}, {}), fast step {}, slow step {}", m, x.GetPixel0OfModuleConv(m) % x.GetXPixelsNum(), x.GetPixel0OfModuleConv(m) / x.GetXPixelsNum(), @@ -155,15 +170,19 @@ bool RunDataset(Logger &logger, AcquisitionDeviceGroup &aq_devices, const std::s service.Indexing(x.GetIndexingSettings()); service.RugnuxLive(true, nullptr, 4, 60, false, false, downsample); - // Error, gap and beam-stop pixels of the reader become error pixels of the module frame + // Error, gap and beam-stop pixels of the reader become error pixels of the module frame. Card by card: each + // card's modules of the image, then its dummies (zeros) std::vector frame(x.GetModulesNum() * RAW_MODULE_SIZE); - std::vector frame_u16(frame.size()); + std::vector card_frame(card_x.GetModulesNum() * RAW_MODULE_SIZE); for (int64_t i = 0; i < generator_images; i++) { const auto image = reader.LoadImage(i); SqueezeToRawGeometry(x, frame.data(), image->Image().data(), BEAM_STOP_PXL_VALUE, SATURATED_PXL_VALUE, INT16_MIN, INT16_MAX); - memcpy(frame_u16.data(), frame.data(), frame.size() * sizeof(int16_t)); - service.LoadInternalGeneratorImage(x, frame_u16, i); + for (int d = 0; d < x.GetDataStreamsNum(); d++) + memcpy(card_frame.data() + card_x.GetFirstModuleOfDataStream(d) * RAW_MODULE_SIZE, + frame.data() + x.GetFirstModuleOfDataStream(d) * RAW_MODULE_SIZE, + x.GetModulesNum(d) * RAW_MODULE_SIZE * sizeof(int16_t)); + service.LoadInternalGeneratorImage(card_x, card_frame, i); } struct Row { @@ -176,7 +195,7 @@ bool RunDataset(Logger &logger, AcquisitionDeviceGroup &aq_devices, const std::s for (const double rate: rates) { // Blocking at source: the puller waits for a free slot and the receiver for room in the image buffer, // the cards hold their frames and their generators stall - service.FPGAImagePullerSettings(puller_slots, !dropping, rate); + service.FPGAImagePullerSettings(puller_slots, !dropping, rate, false, modules_per_card); logger.Info(""); logger.Info("=== FPGAImagePuller ({} slots, {}), {} ===", puller_slots, dropping ? "dropping" : "blocking", (rate > 0) ? fmt::format("source paced at {:.1f} Hz", rate) : std::string("source as fast as it goes")); @@ -309,11 +328,12 @@ int main(int argc, char **argv) { bool verbose = false; std::vector rates = {0}; bool dropping = false; + bool pad = true; int64_t downsample = 1; std::optional space_group; int opt; - while ((opt = getopt(argc, argv, "vi:s:N:B:C:S:X:t:r:p:dk:K::")) != -1) { + while ((opt = getopt(argc, argv, "vi:s:N:B:C:S:X:t:r:p:dUk:K::")) != -1) { switch (opt) { case 'v': verbose = true; @@ -366,6 +386,9 @@ int main(int argc, char **argv) { case 'd': dropping = true; break; + case 'U': + pad = false; + break; case 'k': downsample = atol(optarg); break; @@ -419,7 +442,7 @@ int main(int argc, char **argv) { bool ret = false; try { ret = RunDataset(logger, aq_devices, argv[optind], nimages, nstreams, nthreads, send_buffer_size_MiB, - i_settings, cell, puller_slots, rates, dropping, downsample, space_group); + i_settings, cell, puller_slots, rates, dropping, pad, downsample, space_group); } catch (std::exception &e) { logger.Error(e.what()); } From 1b76b4539e452c37e8f78d0527644d238f3e7c77 Mon Sep 17 00:00:00 2001 From: Filip Leonarski Date: Wed, 18 Nov 2026 15:33:51 +0100 Subject: [PATCH 22/41] jfjoch_fpga_stills_test -v: progress lines only, the debug log stays off -v raised the logger to debug, which the devices use for two lines per module frame: 2.25 M lines and 570 MB in 56 s on the server's four cards, until its disk filled. -v now prints only the 0.5 s progress lines; the debug log is off. The completion line of FPGAAcquisitionDevice::ReadWorkCompletionThread goes: its frame and module are read from the buffer only later, so it printed 0 for both (WaitForActionComplete's line has them). Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01UqXYdHHZ4cogS1mrGUtfN7 --- acquisition_device/FPGAAcquisitionDevice.cpp | 9 +-------- tools/jfjoch_fpga_stills_test.cpp | 14 ++++++++------ 2 files changed, 9 insertions(+), 14 deletions(-) diff --git a/acquisition_device/FPGAAcquisitionDevice.cpp b/acquisition_device/FPGAAcquisitionDevice.cpp index f7b24a08b..f866807c3 100644 --- a/acquisition_device/FPGAAcquisitionDevice.cpp +++ b/acquisition_device/FPGAAcquisitionDevice.cpp @@ -40,15 +40,8 @@ void FPGAAcquisitionDevice::ReadWorkCompletionThread() { } if (read) { + // Frame and module of an image completion are read from its buffer later (WaitForActionComplete) c = parse_hw_completion(values); - if (logger) { - logger->Debug("Stream {} Completion data collection ID {} type {} frame {} module {}", - data_stream, - c.data_collection_id, - (int)c.type, - c.frame_number, - c.module_number); - } if (c.data_collection_id == data_collection_id) { work_completion_queue.PutBlocking(c); if (c.type == Completion::Type::End) diff --git a/tools/jfjoch_fpga_stills_test.cpp b/tools/jfjoch_fpga_stills_test.cpp index eb6254a77..32552fd30 100644 --- a/tools/jfjoch_fpga_stills_test.cpp +++ b/tools/jfjoch_fpga_stills_test.cpp @@ -31,7 +31,7 @@ void print_usage(Logger &logger) { logger.Info("loaded into the cards' internal generators, which cycle through them: images repeat, so throughput, latency"); logger.Info("and indexing rate are meaningful, the merge and its statistics are not. See docs/TOOLS.md."); logger.Info("Options:"); - logger.Info(" -v Verbose, with each card's progress every 0.5 s"); + logger.Info(" -v Each card's progress, the receiver's and the analysis' counts every 0.5 s"); logger.Info(" -i Images in the run (default: as many as the file has)"); logger.Info(" -s Number of data streams (cards)"); logger.Info(" -N Number of image processing threads (default 64)"); @@ -93,7 +93,7 @@ int64_t GeneratorImages(AcquisitionDeviceGroup &aq_devices, const DiffractionExp bool RunDataset(Logger &logger, AcquisitionDeviceGroup &aq_devices, const std::string &file, std::optional nimages, uint16_t nstreams, uint16_t nthreads, size_t send_buffer_size_MiB, const IndexingSettings &indexing, const std::optional &cell, size_t puller_slots, - const std::vector &rates, bool dropping, bool pad, int64_t downsample, + const std::vector &rates, bool dropping, bool pad, bool verbose, int64_t downsample, const std::optional &space_group) { RegisterHDF5Filter(); JFJochHDF5Reader reader; @@ -223,8 +223,9 @@ bool RunDataset(Logger &logger, AcquisitionDeviceGroup &aq_devices, const std::s if (live.stills) line += fmt::format(" stills: held {} analysed {} pre-pass {}", live.stills->images_held, live.stills->images_analysed, static_cast(live.stills->prepass)); - logger.Debug("{:.1f} s{}", std::chrono::duration(std::chrono::steady_clock::now() - - wall_start).count(), line); + if (verbose) + logger.Info("{:.1f} s{}", std::chrono::duration(std::chrono::steady_clock::now() + - wall_start).count(), line); } }); const auto output = service.Stop(); @@ -421,7 +422,8 @@ int main(int argc, char **argv) { exit(EXIT_FAILURE); } - logger.Verbose(verbose); + // -v gives the progress lines only: the debug log has a line for every module frame + logger.Verbose(false); AcquisitionDeviceGroup aq_devices; for (int i = 0; i < nstreams; i++) { @@ -442,7 +444,7 @@ int main(int argc, char **argv) { bool ret = false; try { ret = RunDataset(logger, aq_devices, argv[optind], nimages, nstreams, nthreads, send_buffer_size_MiB, - i_settings, cell, puller_slots, rates, dropping, pad, downsample, space_group); + i_settings, cell, puller_slots, rates, dropping, pad, verbose, downsample, space_group); } catch (std::exception &e) { logger.Error(e.what()); } From bb6354252c0931f75436e65cd5ba734d900e264b Mon Sep 17 00:00:00 2001 From: Filip Leonarski Date: Wed, 18 Nov 2026 16:13:40 +0100 Subject: [PATCH 23/41] Live stills: analysis threads per GPU as offline rugnux; stills test indexer pool 8 The live stills analysis took min(16, threads) threads whatever the cards. It now takes what offline rugnux's per-image loop takes (ImageWorkers): 16 a card, fewer on a card too small for 16 workers' engines (half its memory, about 24 bytes a detector pixel each, GPUWorkersPerCard), at most the threads given; without a GPU, the threads given. Both now come from free functions in Rugnux.h that the Rugnux members call. The indexer pool stays the broker's (indexing settings thread_count, default 4): it is shared with the per-image analysis and its GPU indexers are built once for the broker's life. jfjoch_fpga_stills_test -t defaults to 8, as offline rugnux on stills (StillsIndexerThreads). On this host (one GPU) the thread count does not change (16); on a server with 4 cards it is 64, at most -N. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01UqXYdHHZ4cogS1mrGUtfN7 --- receiver/JFJochReceiverRugnuxStills.cpp | 4 +++- rugnux/Rugnux.h | 6 ++++++ rugnux/RugnuxImagePass.cpp | 21 +++++++++++++++------ tools/jfjoch_fpga_stills_test.cpp | 4 ++-- 4 files changed, 26 insertions(+), 9 deletions(-) diff --git a/receiver/JFJochReceiverRugnuxStills.cpp b/receiver/JFJochReceiverRugnuxStills.cpp index 59b634bdb..a4133b54a 100644 --- a/receiver/JFJochReceiverRugnuxStills.cpp +++ b/receiver/JFJochReceiverRugnuxStills.cpp @@ -8,6 +8,7 @@ #include "../common/time_utc.h" #include "../frame_serialize/CBORStream2Serializer.h" +#include "../rugnux/Rugnux.h" #include "../rugnux/RugnuxDefaults.h" #include "RugnuxStructure.h" #include "StillsSelection.h" @@ -39,7 +40,8 @@ JFJochReceiverRugnuxStills::JFJochReceiverRugnuxStills(const DiffractionExperime downsample(in_downsample), live_status(in_live_status), indexing_thread_pool(in_indexing_thread_pool), - stills_nthreads(std::min(16, in_forward_nthreads)) { + // As offline rugnux's per-image loop: 16 a card, at most the threads given + stills_nthreads(ImageWorkers(in_experiment.GetPixelsNum(), static_cast(in_forward_nthreads))) { StartThreads(); } diff --git a/rugnux/Rugnux.h b/rugnux/Rugnux.h index 519c68ade..28d0d9e27 100644 --- a/rugnux/Rugnux.h +++ b/rugnux/Rugnux.h @@ -83,6 +83,12 @@ enum class ProcessMode { // Where the per-image analysis of an output pass goes as it is made: rugnux and the viewer put it in // _process.h5 (ProcessFileSink, RugnuxOutputFiles.h). Called from one thread at a time. +// The image workers a card takes: as many as keep half of its memory (about 24 bytes a detector pixel each), at most +// `most` (Rugnux::GPUWorkersPerCard); and those of a per-image loop: 16 a card, at most nthreads, nthreads without a +// GPU (Rugnux::ImageWorkers). Also the live stills analysis's. +int GPUWorkersPerCard(int64_t pixels, int most); +int ImageWorkers(int64_t pixels, int nthreads); + class RugnuxImageSink { public: virtual ~RugnuxImageSink() = default; diff --git a/rugnux/RugnuxImagePass.cpp b/rugnux/RugnuxImagePass.cpp index 872ea5145..cdb00ddb6 100644 --- a/rugnux/RugnuxImagePass.cpp +++ b/rugnux/RugnuxImagePass.cpp @@ -88,13 +88,16 @@ using namespace rugnux_internal; // detector, measured at 12-22 bytes a pixel on four data sets - and the workers keep to half of the card, // so a small card gets fewer of them. How many there are changes only how fast a loop runs, never what it // computes. -int Rugnux::GPUWorkersPerCard(int most) const { +int GPUWorkersPerCard(int64_t pixels, int most) { constexpr int64_t WORKER_BYTES_PER_PIXEL = 24; - const auto fit = static_cast(get_gpu_total_memory(0) / 2) - / (WORKER_BYTES_PER_PIXEL * experiment_.GetPixelsNum()); + const auto fit = static_cast(get_gpu_total_memory(0) / 2) / (WORKER_BYTES_PER_PIXEL * pixels); return static_cast(std::clamp(fit, 1, most)); } +int Rugnux::GPUWorkersPerCard(int most) const { + return ::GPUWorkersPerCard(experiment_.GetPixelsNum(), most); +} + // Every worker submits its own kernels to a card, and a card runs out of room to accept them long before it // runs out of work: measured on two GPUs, the image loop's own time falls to sixteen workers and then rises // again, so forty-eight is slower than sixteen on a 16 Mpx set. Sixteen is where that measurement put the @@ -103,11 +106,17 @@ int Rugnux::GPUWorkersPerCard(int most) const { // was left at its default - an explicit -N is a deliberate instruction and is obeyed, which is what a // previous attempt at this got wrong. A worker also holds GPU memory, so a small card gets fewer of them // (GPUWorkersPerCard). -int Rugnux::ImageWorkers() const { +int ImageWorkers(int64_t pixels, int nthreads) { const int gpus = get_gpu_count(); - if (!config_.nthreads_auto || gpus == 0) + if (gpus == 0) + return nthreads; + return std::min(nthreads, GPUWorkersPerCard(pixels, 16) * gpus); +} + +int Rugnux::ImageWorkers() const { + if (!config_.nthreads_auto) return config_.nthreads; - return std::min(config_.nthreads, GPUWorkersPerCard(16) * gpus); + return ::ImageWorkers(experiment_.GetPixelsNum(), config_.nthreads); } void Rugnux::ImagePass(PipelineLocals &p) { diff --git a/tools/jfjoch_fpga_stills_test.cpp b/tools/jfjoch_fpga_stills_test.cpp index 32552fd30..46f20f0bb 100644 --- a/tools/jfjoch_fpga_stills_test.cpp +++ b/tools/jfjoch_fpga_stills_test.cpp @@ -39,7 +39,7 @@ void print_usage(Logger &logger) { logger.Info(" -C Unit cell (default: the file's)"); logger.Info(" -S Space group of the collection (a space group stored in the file is ignored)"); logger.Info(" -X Indexing (auto|fft|fftw|ffbidx), auto is default"); - logger.Info(" -t Indexing thread pool size (default: 4)"); + logger.Info(" -t Indexing thread pool size (default: 8, as offline rugnux on stills; the broker's default is 4)"); logger.Info(" -r Rates the source is paced at, one collection each (default: 0 = as fast as it goes); the"); logger.Info(" host takes frame i no earlier than i/rate, the card waits meanwhile: blocking runs only"); logger.Info(" -p FPGAImagePuller slots (default 128)"); @@ -323,7 +323,7 @@ int main(int argc, char **argv) { std::optional nimages; std::optional cell; IndexingAlgorithmEnum indexing = IndexingAlgorithmEnum::Auto; - uint16_t indexing_threads = 4; + uint16_t indexing_threads = 8; // as offline rugnux's stills (Rugnux::StillsIndexerThreads) size_t puller_slots = FPGAImagePuller::DefaultSlots; std::optional mock_card_MiB; bool verbose = false; From 38137e16a0794a31ddf35daded924b355a8a944b Mon Sep 17 00:00:00 2001 From: Filip Leonarski Date: Wed, 18 Nov 2026 16:26:01 +0100 Subject: [PATCH 24/41] Live stills: the frames waiting for the analysis inside the image buffer, at most half of it Lane l's hold (702b8d4a6) kept a frame that found no free slot as a heap copy of its compressed bytes, up to the image buffer's size again - up to twice the configured image memory. Now every waiting frame is held as its compressed bytes packed into slots of the image buffer (HoldArena): several frames to a slot, at most half of the slots, the slots kept for the analysis threads to send with left alone; a slot is reused once its frames are gone, and the slots go back before the image buffer is checked at the end. A frame that finds the waiting half full is dropped and counted as before (blocking: waits). The receiver's image memory is the image buffer (image_buffer_MiB of the broker, -B of the stills test) and nothing beside it; the broker takes the same receiver. The frames are no longer serialised into a slot of their own while they wait, so the broker's image routes show a frame once it is analysed. HoldArenaTest: half of the slots at most, three frames of a third of a slot each to a slot, nothing larger than a slot, a freed slot reused, all slots back after ReleaseSlots. jfjoch_fpga_stills_test prints the process's maximum resident memory. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01UqXYdHHZ4cogS1mrGUtfN7 --- docs/JFJOCH_BROKER.md | 9 ++- receiver/HoldArena.h | 90 +++++++++++++++++++++++++ receiver/JFJochReceiverRugnuxStills.cpp | 63 +++++------------ receiver/JFJochReceiverRugnuxStills.h | 11 ++- receiver/StillsPrePass.h | 14 ++-- tests/CMakeLists.txt | 1 + tests/HoldArenaTest.cpp | 40 +++++++++++ tools/jfjoch_fpga_stills_test.cpp | 5 +- 8 files changed, 168 insertions(+), 65 deletions(-) create mode 100644 receiver/HoldArena.h create mode 100644 tests/HoldArenaTest.cpp diff --git a/docs/JFJOCH_BROKER.md b/docs/JFJOCH_BROKER.md index 24599c00f..fcfeda74f 100644 --- a/docs/JFJOCH_BROKER.md +++ b/docs/JFJOCH_BROKER.md @@ -373,9 +373,12 @@ of its frames indexed, as with a small image buffer, a low hit rate or a chip wh cell given), the distance in the header is used for the whole run: this is a warning in the log and a note of the live status, and a wrong header distance then costs resolution and indexed frames. -Frames arriving during the pre-pass, or faster than the analysis, wait in the image buffer, in all its slots but -one per analysis thread, kept for sending; a frame that finds it full is dropped and counted as for a full image -buffer, so analysis slower than the frame rate costs frames, not memory. Where the writer lags behind, the analysis +Frames arriving during the pre-pass, or faster than the analysis, wait in the image buffer as their compressed bytes, +packed into at most half of its slots (several frames to a slot); the other half is for the analysed frames, which go +to the writer from a slot each, with one slot kept per analysis thread. The receiver's image memory is the image +buffer (`image_buffer_MiB`, `-B` of `jfjoch_fpga_stills_test`) and nothing beside it. A frame that finds the waiting +half full is dropped and counted as for a full image buffer, so analysis slower than the frame rate costs frames, +not memory. Where the writer lags behind, the analysis waits for slots to come back. A pre-pass that fails leaves the stated geometry and mask in use. Where the start message cannot be sent after the pre-pass (no writer listening) or the analysis cannot be set up, the collection ends with that error, reported by `/status` and `/wait_till_done`, and the diff --git a/receiver/HoldArena.h b/receiver/HoldArena.h new file mode 100644 index 000000000..ebfeaf5b7 --- /dev/null +++ b/receiver/HoldArena.h @@ -0,0 +1,90 @@ +// SPDX-FileCopyrightText: 2026 Filip Leonarski, Paul Scherrer Institute +// SPDX-License-Identifier: GPL-3.0-only + +#pragma once + +#include +#include +#include +#include + +#include "../common/ImageBuffer.h" +#include "../common/ZeroCopyReturnValue.h" + +// The frames waiting for the analysis, as their compressed bytes packed into slots of the image buffer: inside its +// memory, at most `max_slots` of its slots (half of them in the stills receiver), and the slots kept free for sending +// left alone. A slot is reused once the frames in it are all released; with every slot taken and full, Allocate fails. +class HoldArena { + struct Chunk { + ZeroCopyReturnValue *slot; + size_t used = 0; + int64_t frames = 0; + }; + ImageBuffer &image_buffer; + const int64_t max_slots; + const int64_t keep_free; + const size_t slot_size; + std::mutex m; + std::vector chunks; + size_t current = SIZE_MAX; +public: + struct Region { + uint8_t *data = nullptr; + std::function release; // once the frame is gone + }; + + HoldArena(ImageBuffer &in_image_buffer, int64_t in_max_slots, int64_t in_keep_free, size_t in_slot_size) + : image_buffer(in_image_buffer), max_slots(in_max_slots), keep_free(in_keep_free), slot_size(in_slot_size) {} + + ~HoldArena() { ReleaseSlots(); } + + // The slots go back to the image buffer: once no frame is held any more + void ReleaseSlots() { + std::unique_lock ul(m); + for (auto &c: chunks) + if (c.slot) { + c.slot->discard(); + c.slot = nullptr; + } + current = SIZE_MAX; + } + + // Empty where there is no room + Region Allocate(size_t size) { + std::unique_lock ul(m); + if (size > slot_size) + return {}; + if (current == SIZE_MAX || chunks[current].used + size > slot_size) { + current = SIZE_MAX; + for (size_t i = 0; i < chunks.size(); i++) + if (chunks[i].slot && chunks[i].frames == 0) { + chunks[i].used = 0; + current = i; + break; + } + if (current == SIZE_MAX && static_cast(chunks.size()) < max_slots) { + if (auto slot = image_buffer.GetImageSlot(keep_free)) { + chunks.push_back(Chunk{.slot = slot}); + current = chunks.size() - 1; + } + } + if (current == SIZE_MAX) + return {}; + } + Chunk &c = chunks[current]; + Region ret{.data = static_cast(c.slot->GetImage()) + c.used}; + c.used += size; + c.frames++; + const size_t index = current; + ret.release = [this, index] { + std::unique_lock ul2(m); + chunks[index].frames--; + }; + return ret; + } + + int64_t GetSlotsUsed() { + std::unique_lock ul(m); + return static_cast(chunks.size()); + } +}; diff --git a/receiver/JFJochReceiverRugnuxStills.cpp b/receiver/JFJochReceiverRugnuxStills.cpp index a4133b54a..d9ed53f50 100644 --- a/receiver/JFJochReceiverRugnuxStills.cpp +++ b/receiver/JFJochReceiverRugnuxStills.cpp @@ -52,8 +52,10 @@ JFJochReceiverRugnuxStills::~JFJochReceiverRugnuxStills() { void JFJochReceiverRugnuxStills::OnStart(std::chrono::steady_clock::time_point received) { const int64_t slots = image_buffer.GetStatus().total_slots; - stills_keep_free = std::min(stills_nthreads, slots / 2); - copy_budget = slots * experiment.GetImageBufferLocationSize(); + // The frames that wait take at most half of the image buffer; the other half is for those analysed, sent from + // a slot each, and a slot is kept free for each analysis thread to send with + const int64_t keep_free = std::min(stills_nthreads, slots / 2); + hold_arena = std::make_unique(image_buffer, slots / 2, keep_free, experiment.GetImageBufferLocationSize()); const StartMessage start = MakeStartMessage(experiment, pixel_mask, *az_int_mapping); // The frames are shown from their arrival, on the stated geometry until the pre-pass has decided its own. // To the image buffer only: the writer and the ZeroMQ streams get the one start message, after the pre-pass. @@ -93,59 +95,24 @@ void JFJochReceiverRugnuxStills::OnImage(uint32_t id, DataMessage &message, std: } const size_t size = message.image.GetCompressedSize(); - // Waits for the analysis in a slot of the image buffer, where it can be seen while it waits (it is not sent from - // there); a slot is kept free for each analysis thread to send with. Without a slot, in a copy of its own. + // Waits for the analysis as its compressed bytes, packed into slots of the image buffer (HoldArena) auto held = std::make_shared(); - const auto hold = [&] { - held->slot = image_buffer.GetImageSlot(stills_keep_free); - if (held->slot == nullptr) { - if (copy_bytes.fetch_add(static_cast(size)) + static_cast(size) <= copy_budget) { - held->copy.assign(message.image.GetCompressed(), message.image.GetCompressed() + size); - held->copy_bytes = ©_bytes; - } else - copy_bytes -= static_cast(size); - } - return held->slot != nullptr || held->copy_bytes != nullptr; - }; - bool held_ok = hold(); - while (!held_ok && image_puller.IsBlocking() && !cancelled) { + HoldArena::Region region = hold_arena->Allocate(size); + while (!region.data && image_puller.IsBlocking() && !cancelled) { std::this_thread::sleep_for(std::chrono::milliseconds(1)); - held_ok = hold(); + region = hold_arena->Allocate(size); } - if (!held_ok) { + if (!region.data) { writer_queue_full = true; return; } + memcpy(region.data, message.image.GetCompressed(), size); + held->release = std::move(region.release); held->message = message; StampImage(held->message, image_puller.GetCurrentFifoUtilization()); - - if (held->slot) { - // In the slot as an image without analysis; the analysis reads the image where it is in the slot. - auto slot_buffer = static_cast(held->slot->GetImage()); - CBORStream2Serializer serializer(slot_buffer, experiment.GetImageBufferLocationSize()); - held->message.image = CompressedImage(nullptr, 0, message.image.GetWidth(), message.image.GetHeight(), - message.image.GetMode(), message.image.GetCompressionAlgorithm(), - message.image.GetChannel()); - serializer.SerializeImage(held->message); - const size_t image_offset = serializer.GetImageAppendOffset(); - if (image_offset + size + 32 >= static_cast(experiment.GetImageBufferLocationSize())) { - logger.Error("Dropping image {} - metadata {} B + image {} B do not fit in buffer slot {} B", message.number, - image_offset, size, experiment.GetImageBufferLocationSize()); - return; - } - memcpy(slot_buffer + image_offset, message.image.GetCompressed(), size); - serializer.AppendImage(size); - held->message.image = CompressedImage(slot_buffer + image_offset, size, message.image.GetWidth(), - message.image.GetHeight(), message.image.GetMode(), - message.image.GetCompressionAlgorithm(), message.image.GetChannel()); - held->slot->SetImageNumber(message.number); - held->slot->SetImageSize(serializer.GetBufferSize()); - held->slot->SetIndexed(false); - held->slot->ReadyToSend(); - } else - held->message.image = CompressedImage(held->copy.data(), size, message.image.GetWidth(), - message.image.GetHeight(), message.image.GetMode(), - message.image.GetCompressionAlgorithm(), message.image.GetChannel()); + held->message.image = CompressedImage(region.data, size, message.image.GetWidth(), message.image.GetHeight(), + message.image.GetMode(), message.image.GetCompressionAlgorithm(), + message.image.GetChannel()); stills->Hold(held); } @@ -159,6 +126,8 @@ void JFJochReceiverRugnuxStills::FinishCollection() { } catch (const std::exception &) { error = std::current_exception(); } + // Every frame is analysed: the slots the frames waited in go back, before the image buffer is checked + hold_arena->ReleaseSlots(); current_status.SetProgress(1.0); current_status.SetStatus(GetStatus()); diff --git a/receiver/JFJochReceiverRugnuxStills.h b/receiver/JFJochReceiverRugnuxStills.h index b43f1b4c4..7227e2fe4 100644 --- a/receiver/JFJochReceiverRugnuxStills.h +++ b/receiver/JFJochReceiverRugnuxStills.h @@ -9,6 +9,7 @@ #include "JFJochReceiverStream.h" #include "RugnuxLiveStatus.h" +#include "HoldArena.h" #include "StillsGPUAnalysis.h" // A serial collection analysed frame by frame at the geometry of a pre-pass, which the start message waits for @@ -21,12 +22,10 @@ class JFJochReceiverRugnuxStills : public JFJochReceiverStream, public StillsSin IndexerThreadPool *const indexing_thread_pool; const int64_t stills_nthreads; - int64_t stills_keep_free = 0; // slots frames do not take, for the analysis threads to send with - // Frames that find no free slot while they wait for the analysis are held as their compressed bytes, up to the - // image buffer's size again: the pre-pass holds every frame that arrives before it is over, and a frame is a - // fraction of a slot (1.5 MB of a 24 MB slot on a 9M detector) - int64_t copy_budget = 0; - std::atomic copy_bytes = 0; + // The frames waiting for the analysis, packed as their compressed bytes into at most half of the image + // buffer's slots: a frame is a fraction of a slot (1.5 MB of a 24 MB slot on a 9M detector), and the pre-pass + // holds every frame that arrives before it is over + std::unique_ptr hold_arena; std::mutex stills_mutex; bool cut = false; diff --git a/receiver/StillsPrePass.h b/receiver/StillsPrePass.h index 5f6712c15..b82ce058f 100644 --- a/receiver/StillsPrePass.h +++ b/receiver/StillsPrePass.h @@ -4,6 +4,7 @@ #pragma once #include +#include #include #include #include @@ -15,14 +16,13 @@ #include "../common/ZeroCopyReturnValue.h" #include "../image_analysis/IndexAndRefine.h" // StillsWindow -// An image held until analysed, pointing into `slot`, which goes back unsent with the last copy. The slot is -// forgotten then, so that the copy sent with the analysis is the only one the image buffer finds. Where no slot -// was free, the image points into `copy` instead, its compressed bytes, counted in `copy_bytes` while held. +// An image held until analysed, pointing into `slot`, which goes back unsent with the last copy (the slot is +// forgotten then, so that the copy sent with the analysis is the only one the image buffer finds), or into bytes +// `release` gives back with the last copy (HoldArena). struct HeldImage { DataMessage message; ZeroCopyReturnValue *slot = nullptr; - std::vector copy; - std::atomic *copy_bytes = nullptr; + std::function release; HeldImage() = default; HeldImage(const HeldImage &) = delete; @@ -30,8 +30,8 @@ struct HeldImage { ~HeldImage() { if (slot) slot->discard(); - if (copy_bytes) - *copy_bytes -= static_cast(copy.size()); + if (release) + release(); } }; diff --git a/tests/CMakeLists.txt b/tests/CMakeLists.txt index a48a4ac86..3ae22959c 100644 --- a/tests/CMakeLists.txt +++ b/tests/CMakeLists.txt @@ -156,6 +156,7 @@ ADD_EXECUTABLE(jfjoch_test JFJochReceiverRugnuxTest.cpp FPGAImagePullerTest.cpp StillsSelectionTest.cpp + HoldArenaTest.cpp GridScanSettingsTest.cpp JFJochReceiverPlotsTest.cpp GoniometerAxisTest.cpp diff --git a/tests/HoldArenaTest.cpp b/tests/HoldArenaTest.cpp new file mode 100644 index 000000000..e9414d4dc --- /dev/null +++ b/tests/HoldArenaTest.cpp @@ -0,0 +1,40 @@ +// SPDX-FileCopyrightText: 2026 Filip Leonarski, Paul Scherrer Institute +// SPDX-License-Identifier: GPL-3.0-only + +#include + +#include "../receiver/HoldArena.h" + +TEST_CASE("HoldArena_WithinHalfOfTheImageBuffer", "[HoldArena]") { + constexpr size_t slot_size = 1024 * 1024; + ImageBuffer buffer(64 * slot_size); + buffer.StartMeasurement(slot_size); + const int64_t total = buffer.GetStatus().total_slots; + REQUIRE(total >= 32); + + std::vector held; + { + HoldArena arena(buffer, total / 2, 4, slot_size); + // Frames of a third of a slot: three to a slot, half of the slots at most + while (true) { + auto r = arena.Allocate(slot_size / 3); + if (!r.data) + break; + held.push_back(std::move(r)); + } + CHECK(arena.GetSlotsUsed() == total / 2); + CHECK(held.size() == static_cast(3 * (total / 2))); + CHECK(buffer.GetSlotStatus().available_slots == total - total / 2); + // Larger than a slot: never held + CHECK(!arena.Allocate(slot_size + 1).data); + + // A slot whose frames are all gone is reused, nothing more is taken from the buffer + for (int i = 0; i < 3; i++) + held[i].release(); + CHECK(arena.Allocate(slot_size / 3).data != nullptr); + CHECK(arena.GetSlotsUsed() == total / 2); + + arena.ReleaseSlots(); + CHECK(buffer.GetSlotStatus().available_slots == total); + } +} diff --git a/tools/jfjoch_fpga_stills_test.cpp b/tools/jfjoch_fpga_stills_test.cpp index 46f20f0bb..38cf67851 100644 --- a/tools/jfjoch_fpga_stills_test.cpp +++ b/tools/jfjoch_fpga_stills_test.cpp @@ -258,9 +258,10 @@ bool RunDataset(Logger &logger, AcquisitionDeviceGroup &aq_devices, const std::s output.status.images_dropped, output.efficiency); logger.Info("Delivered {:.1f} Hz (first to last image {:.2f} s), source blocked {:.1f}% of it", delivered_hz, delivery_s, 100.0 * blocked); - logger.Info("Sustained {:.1f} Hz (images / wall time {:.2f} s, start to analysis done) CPU {:.1f} s = {:.1f} cores", + logger.Info("Sustained {:.1f} Hz (images / wall time {:.2f} s, start to analysis done) CPU {:.1f} s = {:.1f} cores" + " max resident memory {:.1f} GiB", static_cast(output.status.images_collected) / wall_time, wall_time, cpu_time, - cpu_time / wall_time); + cpu_time / wall_time, static_cast(usage_end.ru_maxrss) / (1024.0 * 1024.0)); // The card's own count of the cycles (200 MHz) it waited for a host buffer, i.e. was held by the host for (int i = 0; i < x.GetDataStreamsNum(); i++) { const auto status = aq_devices[i].GetDataCollectionStatus(); From 521c50de42b7e5571e4f471914b73627a4761070 Mon Sep 17 00:00:00 2001 From: Filip Leonarski Date: Wed, 18 Nov 2026 16:26:01 +0100 Subject: [PATCH 25/41] stills_downsample: images not chosen are written, without their analysis; reset by POST /initialize An image not chosen went neither to the analysis nor to the writer. It now waits with the others and goes to the writer as it came, without its analysis (HeldImage::analyse): images_sent equals the images collected again; the analysed and indexed counts and the merge are of the images analysed. POST /initialize resets stills_downsample to 1, as force_still and refine_solvent. The OpenAPI text and the broker docs say both, and that the first 2000 images (the pre-pass's largest sample, StillsGPUAnalysis::PREPASS_MAX_IMAGES) are all analysed. C++ model, frontend client and python client docs regenerated. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01UqXYdHHZ4cogS1mrGUtfN7 --- broker/JFJochStateMachine.cpp | 1 + broker/gen/model/Rugnux_settings.h | 2 +- broker/jfjoch_api.yaml | 4 ++-- docs/JFJOCH_BROKER.md | 4 ++-- docs/python_client/docs/RugnuxSettings.md | 2 +- frontend/src/client/types.gen.ts | 4 ++-- receiver/JFJochReceiverRugnuxStills.cpp | 7 ++----- receiver/StillsGPUAnalysis.cpp | 13 ++++++------- receiver/StillsGPUAnalysis.h | 1 + receiver/StillsPrePass.h | 1 + 10 files changed, 19 insertions(+), 20 deletions(-) diff --git a/broker/JFJochStateMachine.cpp b/broker/JFJochStateMachine.cpp index 67c72d22e..708153f42 100644 --- a/broker/JFJochStateMachine.cpp +++ b/broker/JFJochStateMachine.cpp @@ -343,6 +343,7 @@ void JFJochStateMachine::Initialize() { s.enable = false; s.refine_solvent = false; s.force_still = false; + s.stills_downsample = 1; s.model = nullptr; s.model_size_bytes = 0; services.SetRugnuxLive(s); diff --git a/broker/gen/model/Rugnux_settings.h b/broker/gen/model/Rugnux_settings.h index 4e2ad0b49..e79daed34 100644 --- a/broker/gen/model/Rugnux_settings.h +++ b/broker/gen/model/Rugnux_settings.h @@ -93,7 +93,7 @@ public: bool forceStillIsSet() const; void unsetForce_still(); /// - /// Serial collections: analyse on average 1 of every this many images, to keep up with a fast stream. Each image is chosen on its own with probability 1 / stills_downsample from a hash of its number - not a stride, which would be in step with periodic patterns (pump-probe on/off, storage cells). The images the pre-pass may use (the first 2000) are all analysed. Images not chosen are counted, not analysed and not written. 1: every image. + /// Serial collections: analyse on average 1 of every this many images, to keep up with a fast stream. Each image is chosen on its own with probability 1 / stills_downsample from a hash of its number - not a stride, which would be in step with periodic patterns (pump-probe on/off, storage cells). The images the pre-pass may use (the first 2000, its largest sample) are all analysed. Images not chosen are written as they came, without their analysis. 1: every image. Reset to 1 by `POST /initialize`. /// int64_t getStillsDownsample() const; void setStillsDownsample(int64_t const value); diff --git a/broker/jfjoch_api.yaml b/broker/jfjoch_api.yaml index e74abf13d..8157bb7e4 100644 --- a/broker/jfjoch_api.yaml +++ b/broker/jfjoch_api.yaml @@ -2851,8 +2851,8 @@ components: Serial collections: analyse on average 1 of every this many images, to keep up with a fast stream. Each image is chosen on its own with probability 1 / stills_downsample from a hash of its number - not a stride, which would be in step with periodic patterns (pump-probe on/off, storage cells). The images the pre-pass - may use (the first 2000) are all analysed. Images not chosen are counted, not analysed and not written. - 1: every image. + may use (the first 2000, its largest sample) are all analysed. Images not chosen are written as they came, + without their analysis. 1: every image. Reset to 1 by `POST /initialize`. rugnux_status: type: object required: diff --git a/docs/JFJOCH_BROKER.md b/docs/JFJOCH_BROKER.md index fcfeda74f..d13c178c8 100644 --- a/docs/JFJOCH_BROKER.md +++ b/docs/JFJOCH_BROKER.md @@ -285,8 +285,8 @@ The analysis takes the frames without the goniometer; the master file keeps it. with a stream faster than the analysis. Each image is chosen on its own, with probability 1 / `stills_downsample` from a hash of its number: not every n-th image, which would be in step with a periodic pattern of the stream (pump-probe on/off, storage cells) and could take, for example, only the dark frames. The choice is reproducible. -The first 2000 images, which the pre-pass may use, are all analysed. An image not chosen is counted as collected, -neither analysed nor written - as an image the serial filter leaves out. +The first 2000 images, the largest sample the pre-pass may use, are all analysed. An image not chosen is written as it +came, without its analysis. Reset to 1 by `POST /initialize`, as `force_still` and `refine_solvent` are. The end message, and with it the end of the collection, waits for the analysis. `deadline_s` (default 60 s; 0 for no cutoff) bounds that wait: this long after the last image the analysis is cut. `POST /cancel` is diff --git a/docs/python_client/docs/RugnuxSettings.md b/docs/python_client/docs/RugnuxSettings.md index f804fc37a..a486dbf47 100644 --- a/docs/python_client/docs/RugnuxSettings.md +++ b/docs/python_client/docs/RugnuxSettings.md @@ -11,7 +11,7 @@ Name | Type | Description | Notes **deadline_s** | **float** | Fixed cutoff: this long after the last image the analysis is cut, and the collection ends with what it has established (as `POST /cancel` after the last image does). 0 means no cutoff. | [optional] [default to 60.0] **refine_solvent** | **bool** | With a model: the refinement also builds the solvent - waters added at difference-map peaks and removed where the maps no longer hold them, waters and ions relabelled (as `rugnux --refine-solvent`). Reset to false by `POST /initialize`. | [optional] [default to False] **force_still** | **bool** | Process DECTRIS rotation collections as stills, on the serial path (pre-pass, GPU analysis, stills merge), as `rugnux --force-still` does. The written file keeps its goniometer. Reset to false by `POST /initialize`. | [optional] [default to False] -**stills_downsample** | **int** | Serial collections: analyse on average 1 of every this many images, to keep up with a fast stream. Each image is chosen on its own with probability 1 / stills_downsample from a hash of its number - not a stride, which would be in step with periodic patterns (pump-probe on/off, storage cells). The images the pre-pass may use (the first 2000) are all analysed. Images not chosen are counted, not analysed and not written. 1: every image. | [optional] [default to 1] +**stills_downsample** | **int** | Serial collections: analyse on average 1 of every this many images, to keep up with a fast stream. Each image is chosen on its own with probability 1 / stills_downsample from a hash of its number - not a stride, which would be in step with periodic patterns (pump-probe on/off, storage cells). The images the pre-pass may use (the first 2000, its largest sample) are all analysed. Images not chosen are written as they came, without their analysis. 1: every image. Reset to 1 by `POST /initialize`. | [optional] [default to 1] ## Example diff --git a/frontend/src/client/types.gen.ts b/frontend/src/client/types.gen.ts index fc32c424a..049d8cfe9 100644 --- a/frontend/src/client/types.gen.ts +++ b/frontend/src/client/types.gen.ts @@ -2049,8 +2049,8 @@ export type rugnux_settings = { * Serial collections: analyse on average 1 of every this many images, to keep up with a fast stream. Each * image is chosen on its own with probability 1 / stills_downsample from a hash of its number - not a stride, * which would be in step with periodic patterns (pump-probe on/off, storage cells). The images the pre-pass - * may use (the first 2000) are all analysed. Images not chosen are counted, not analysed and not written. - * 1: every image. + * may use (the first 2000, its largest sample) are all analysed. Images not chosen are written as they came, + * without their analysis. 1: every image. Reset to 1 by `POST /initialize`. * */ stills_downsample?: number; diff --git a/receiver/JFJochReceiverRugnuxStills.cpp b/receiver/JFJochReceiverRugnuxStills.cpp index d9ed53f50..82dc8c559 100644 --- a/receiver/JFJochReceiverRugnuxStills.cpp +++ b/receiver/JFJochReceiverRugnuxStills.cpp @@ -88,11 +88,6 @@ void JFJochReceiverRugnuxStills::OnImage(uint32_t id, DataMessage &message, std: } live_status.ImageReceived(received); CountImage(message); - // Not analysed and not written, as an image the serial filter leaves out - if (!StillsImageSelected(message.number, downsample, StillsGPUAnalysis::PREPASS_MAX_IMAGES)) { - ++images_skipped; - return; - } const size_t size = message.image.GetCompressedSize(); // Waits for the analysis as its compressed bytes, packed into slots of the image buffer (HoldArena) @@ -108,6 +103,8 @@ void JFJochReceiverRugnuxStills::OnImage(uint32_t id, DataMessage &message, std: } memcpy(region.data, message.image.GetCompressed(), size); held->release = std::move(region.release); + // Not chosen (stills_downsample): written as it came, without its analysis + held->analyse = StillsImageSelected(message.number, downsample, StillsGPUAnalysis::PREPASS_MAX_IMAGES); held->message = message; StampImage(held->message, image_puller.GetCurrentFifoUtilization()); held->message.image = CompressedImage(region.data, size, message.image.GetWidth(), message.image.GetHeight(), diff --git a/receiver/StillsGPUAnalysis.cpp b/receiver/StillsGPUAnalysis.cpp index 83ea397b0..3dfb01ddb 100644 --- a/receiver/StillsGPUAnalysis.cpp +++ b/receiver/StillsGPUAnalysis.cpp @@ -332,7 +332,7 @@ void StillsGPUAnalysis::AnalysisThread() { const auto start_time = std::chrono::steady_clock::now(); profile.emplace(*setup.mapping); try { - if (analysis) + if (analysis && held->analyse) analysis->AnalyzeStreamImage(message, *profile, sink.AnalysisSettings()); } catch (const JFJochException &e) { // The frame is still written, without its analysis. @@ -344,16 +344,15 @@ void StillsGPUAnalysis::AnalysisThread() { - start_time).count(); try { sink.SendAnalysedImage(message, *profile); - if (merge) - merge_queue.Put(message.number); - int64_t analysed; - { + if (held->analyse) { + if (merge) + merge_queue.Put(message.number); std::unique_lock ul(live_mutex); - analysed = ++live.images_analysed; + ++live.images_analysed; if (message.indexing_result.value_or(false)) ++live.images_indexed; } - status.Progress(analysed, experiment.GetImageNum()); + status.Progress(++images_done, experiment.GetImageNum()); Publish(); } catch (const std::exception &e) { // The thread goes on with the next frame, so that the queue is drained. diff --git a/receiver/StillsGPUAnalysis.h b/receiver/StillsGPUAnalysis.h index bbc87e36a..fd85e4711 100644 --- a/receiver/StillsGPUAnalysis.h +++ b/receiver/StillsGPUAnalysis.h @@ -146,6 +146,7 @@ private: std::condition_variable model_cv; std::optional model_next; std::atomic step_cut{false}; // the step running is cut + std::atomic images_done{0}; // sent, analysed or not bool model_stop = false; bool model_cut = false; // the steps from here on are cut too bool model_over = false; // the step on the merge of the collection has ended: nothing is left to cut diff --git a/receiver/StillsPrePass.h b/receiver/StillsPrePass.h index b82ce058f..f29098fcc 100644 --- a/receiver/StillsPrePass.h +++ b/receiver/StillsPrePass.h @@ -23,6 +23,7 @@ struct HeldImage { DataMessage message; ZeroCopyReturnValue *slot = nullptr; std::function release; + bool analyse = true; // false: written without its analysis (stills_downsample) HeldImage() = default; HeldImage(const HeldImage &) = delete; From fbf01a39c76b6bf9902fc5e5969a5f83f758fc69 Mon Sep 17 00:00:00 2001 From: Filip Leonarski Date: Wed, 18 Nov 2026 16:35:50 +0100 Subject: [PATCH 26/41] FPGAImagePuller: images assembled per thread from the cards' buffers, no slots The puller had 128 slots, each a whole uncompressed image and a compressed one (about 40 MB on a 9M, 5 GB, allocated and written at every start, no knob), a thread per module writing its module into the slot of each image in flight, and since 0060c734b a further copy of the compressed image. Now, as JFJochReceiverFPGA: each image thread takes the next image, waits for its modules in the cards' buffers (WaitForFrame, the same rules), assembles them into an image of its own, compresses it, and the cards' buffers go back. The cards' buffers are the window over the images in flight; nothing else holds an image. Frames of a module given up on that arrive later go back as soon as they do (ReleaseLateFrames). Dummy modules (CardExperiment) are only returned. The images compressed and waiting for the receiver are bounded by `queue` (default 128, -p of the stills test, the old slot count): not blocking, an image the receiver has no room for is dropped before it is assembled, its frames back at once; blocking, it waits for room (the time is GetQueueWaitTime_s, the source blocked). The warning says the receiver's queue was full, not "no free slot". Per collection on a 9M with N image threads: N x (an uncompressed image + its compressed bound), 64 threads 2.6 GB where 128 slots were 5.2 GB; the queue holds compressed images only. Per image: the modules copied once into the thread's image, compressed once, the compressed bytes copied once into the output (the receiver keeps them) - as before less the slot. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01UqXYdHHZ4cogS1mrGUtfN7 --- receiver/FPGAImagePuller.cpp | 257 ++++++++++------------------- receiver/FPGAImagePuller.h | 64 +++---- receiver/JFJochReceiverService.cpp | 10 +- receiver/JFJochReceiverService.h | 10 +- tests/FPGAImagePullerTest.cpp | 12 +- tools/jfjoch_fpga_stills_test.cpp | 16 +- 6 files changed, 137 insertions(+), 232 deletions(-) diff --git a/receiver/FPGAImagePuller.cpp b/receiver/FPGAImagePuller.cpp index c017651f1..948e02acb 100644 --- a/receiver/FPGAImagePuller.cpp +++ b/receiver/FPGAImagePuller.cpp @@ -9,17 +9,16 @@ FPGAImagePuller::FPGAImagePuller(const DiffractionExperiment &in_experiment, const PixelMask &mask, const JFCalibration *calibration, AcquisitionDeviceGroup &in_devices, - Logger &in_logger, int64_t compression_threads, size_t in_max_slots, + Logger &in_logger, int64_t image_threads, size_t in_queue, bool in_blocking, double in_frame_rate_hz, int64_t modules_per_card) - : ImagePuller(in_max_slots + 2), // as many images as slots, the start and the end message + : ImagePuller(in_queue + 2), // the images waiting, the start and the end message experiment(in_experiment), card_experiment(CardExperiment(in_experiment, modules_per_card)), logger(in_logger), devices(in_devices), - max_slots(in_max_slots), + queue(in_queue), blocking(in_blocking), - frame_rate_hz(in_frame_rate_hz), - image_dropped(experiment.GetImageNum(), 0) { + frame_rate_hz(in_frame_rate_hz) { const int ndatastreams = experiment.GetDataStreamsNum(); if (devices.size() < ndatastreams) throw JFJochException(JFJochExceptionCategory::InputParameterInvalid, @@ -28,7 +27,9 @@ FPGAImagePuller::FPGAImagePuller(const DiffractionExperiment &in_experiment, con for (int m = 0; m < experiment.GetModulesNum(); m++) adu_histogram.emplace_back(std::make_unique()); + given_up.resize(ndatastreams); for (int d = 0; d < ndatastreams; d++) { + given_up[d].resize(card_experiment.GetModulesNum(d)); devices[d].PrepareAction(card_experiment); // Of the modules of the image, not the dummies expected_packets_per_image += devices[d].Counters().GetExpectedPacketsPerImage() @@ -39,10 +40,6 @@ FPGAImagePuller::FPGAImagePuller(const DiffractionExperiment &in_experiment, con if ((experiment.GetDetectorType() != DetectorType::JUNGFRAU) || (modules_per_card > 0)) calibration = nullptr; - // Making a slot is slow and its buffers are written once here: none is made, nor first touched, during the run - for (size_t i = 0; i < max_slots; i++) - free_slots.push_back(std::make_shared(experiment)); - // The receiver's own start message is built from its experiment; this one only says the run has begun. StartMessage start{}; experiment.FillMessage(start); @@ -50,12 +47,8 @@ FPGAImagePuller::FPGAImagePuller(const DiffractionExperiment &in_experiment, con .received = std::chrono::steady_clock::now()}); start_time = std::chrono::steady_clock::now(); - for (int i = 0; i < compression_threads; i++) - compress_futures.emplace_back(std::async(std::launch::async, &FPGAImagePuller::CompressThread, this)); - - for (int d = 0; d < ndatastreams; d++) - for (int m = 0; m < card_experiment.GetModulesNum(d); m++) - module_futures.emplace_back(std::async(std::launch::async, &FPGAImagePuller::ModuleThread, this, d, m)); + for (int i = 0; i < image_threads; i++) + image_futures.emplace_back(std::async(std::launch::async, &FPGAImagePuller::ImageThread, this)); std::latch ready(ndatastreams); for (int d = 0; d < ndatastreams; d++) @@ -82,8 +75,6 @@ FPGAImagePuller::~FPGAImagePuller() { } catch (const std::exception &e) { logger.Error("FPGA image puller teardown failed: {}", e.what()); } - // These hold slots, which go back to this object - outside_fifo.Clear(); } DiffractionExperiment FPGAImagePuller::CardExperiment(const DiffractionExperiment &x, int64_t modules_per_card) { @@ -104,10 +95,8 @@ void FPGAImagePuller::SetError(std::exception_ptr e) { } void FPGAImagePuller::Cancel() { - // An image waiting for a slot or for room in the queue is dropped from here on: after a cancel the receiver takes - // no more images + // An image waiting for room in the queue is dropped from here on: after a cancel the receiver takes no more images cancelled = true; - slot_returned.notify_all(); CancelCards(); } @@ -138,7 +127,7 @@ void FPGAImagePuller::AcquireThread(uint16_t data_stream, const PixelMask &mask, device.StartAction(card_experiment); } catch (...) { SetError(std::current_exception()); - CancelCards(); // the module threads of the other cards have to come out as well + CancelCards(); // the image threads waiting on the other cards have to come out as well ready.count_down(); return; } @@ -159,153 +148,90 @@ int64_t FPGAImagePuller::FastestFrame() const { return ret; } -// Polled: a dead card has to be noticed from the other cards' frames. -// A frame given up on can still arrive, late: its buffer goes back to the card, also while waiting, as the card -// may need it to write the frame waited for. -void FPGAImagePuller::WaitForFrame(uint16_t data_stream, uint16_t module_number, int64_t frame, int64_t &oldest_held) { - auto &device = devices[data_stream]; - const auto &counters = device.Counters(); +// The buffers of frames given up on that have come since go back to the card, which may need them for the frames +// waited for +void FPGAImagePuller::ReleaseLateFrames(uint16_t data_stream, uint16_t module_number) { + std::unique_lock ul(given_up_mutex); + auto &frames = given_up[data_stream][module_number]; + std::erase_if(frames, [&](int64_t f) { + if (!devices[data_stream].Counters().IsAnyPacketCollected(f, module_number)) + return false; + devices[data_stream].FrameBufferRelease(f, module_number); + return true; + }); +} + +// Polled: a dead card has to be noticed from the other cards' frames +bool FPGAImagePuller::WaitForFrame(uint16_t data_stream, uint16_t module_number, int64_t frame) { + const auto &counters = devices[data_stream].Counters(); while (true) { - while ((oldest_held < frame) - && (oldest_held < static_cast(counters.GetCurrFrameNumber(module_number)))) - device.FrameBufferRelease(oldest_held++, module_number); + ReleaseLateFrames(data_stream, module_number); // A frame is complete once the module is two further on, as in JFJochReceiverFPGA if ((static_cast(counters.GetCurrFrameNumber(module_number)) >= frame + 2) - || counters.IsAcquisitionFinished() || failed - || (!blocking && (static_cast(counters.GetFastestFrameNumber()) >= frame + 2 + MissingAfterFrames)) - || (!blocking && (FastestFrame() >= frame + 2 + static_cast(max_slots)))) - return; + || counters.IsAcquisitionFinished() || failed) + break; + if (!blocking && ((static_cast(counters.GetFastestFrameNumber()) >= frame + 2 + MissingAfterFrames) + || (FastestFrame() >= frame + 2 + static_cast(queue)))) + break; std::this_thread::sleep_for(std::chrono::milliseconds(1)); } + if (counters.IsAnyPacketCollected(frame, module_number)) + return true; + std::unique_lock ul(given_up_mutex); + given_up[data_stream][module_number].push_back(frame); + return false; } -// The last frame any card got; waits for all cards, so every module stops at the same image -int64_t FPGAImagePuller::LastFrame() const { - for (int d = 0; d < experiment.GetDataStreamsNum(); d++) - while (!devices[d].Counters().IsAcquisitionFinished() && !failed) - std::this_thread::sleep_for(std::chrono::milliseconds(1)); - return FastestFrame(); -} - -std::shared_ptr FPGAImagePuller::GetSlot(int64_t image_number) { - { - std::unique_lock ul(images_mutex); - std::shared_ptr slot; - while (!slot) { - if (image_dropped[image_number]) - return nullptr; - // Another module may have started the image while this one waited - if (const auto it = images_in_progress.find(image_number); it != images_in_progress.end()) - return it->second; - if (!free_slots.empty()) { - slot = free_slots.back(); - free_slots.pop_back(); - } else if (blocking && !failed && !cancelled) { - const auto t0 = std::chrono::steady_clock::now(); - slot_returned.wait_for(ul, std::chrono::milliseconds(10)); - slot_wait_ns += std::chrono::duration_cast( - std::chrono::steady_clock::now() - t0).count(); - } else { - image_dropped[image_number] = 1; - dropped_images++; - break; - } - } - if (slot) { - slot->image_number = image_number; - slot->metadata = std::make_unique(experiment); - slot->modules_left = static_cast(experiment.GetModulesNum()); - images_in_progress[image_number] = slot; - return slot; - } - } - // Not under images_mutex: Emit takes order_mutex, and a slot going back from under order_mutex takes images_mutex - Emit(image_number, std::nullopt); - return nullptr; -} - -void FPGAImagePuller::ReturnSlot(const std::shared_ptr &slot) { - { - std::unique_lock ul(images_mutex); - free_slots.push_back(slot); - } - slot_returned.notify_one(); -} - -void FPGAImagePuller::ModuleThread(uint16_t data_stream, uint16_t module_number) { +void FPGAImagePuller::ImageThread() { + // One image of its own, assembled and compressed here + FrameTransformation transformation(experiment); try { - auto &device = devices[data_stream]; - const auto &counters = device.Counters(); - const size_t module_abs = experiment.GetFirstModuleOfDataStream(data_stream) + module_number; - int64_t oldest_held = 0; - - for (int64_t image = 0; image < experiment.GetImageNum(); image++) { + for (int64_t image = next_to_take++; image < experiment.GetImageNum() && !failed; image = next_to_take++) { if (frame_rate_hz > 0) std::this_thread::sleep_until(start_time + std::chrono::duration_cast( std::chrono::duration(static_cast(image) / frame_rate_hz))); - WaitForFrame(data_stream, module_number, image, oldest_held); - if (failed) - break; - - if (counters.IsAcquisitionFinished() - && (image > static_cast(counters.GetFastestFrameNumber())) - && (image > LastFrame())) - break; - - const bool collected = counters.IsAnyPacketCollected(image, module_number); - // A dummy module (CardExperiment): its frames only go back to the card - const bool dummy = module_number >= experiment.GetModulesNum(data_stream); - if (const auto slot = dummy ? nullptr : GetSlot(image)) { - if (collected) { - const DeviceOutput *output = device.GetDeviceOutput(image, module_number); - slot->metadata->Process(output); - adu_histogram[module_abs]->Add(*output); - slot->transformation.ProcessModule(output, data_stream); - } else - slot->transformation.FillNotCollectedModule(module_number, data_stream); - - if (--slot->modules_left == 0) { - { - std::unique_lock ul(images_mutex); - images_in_progress.erase(image); + // Not blocking, an image the receiver has no room for is not assembled: its frames go back at once + const bool drop = !blocking && (GetCurrentFifoUtilization() >= queue); + ImageMetadata metadata(experiment); + for (int d = 0; d < experiment.GetDataStreamsNum(); d++) { + auto &device = devices[d]; + for (int m = 0; m < card_experiment.GetModulesNum(d); m++) { + const bool collected = WaitForFrame(d, m, image); + // A dummy module (CardExperiment): its frames only go back to the card + if (!drop && m < experiment.GetModulesNum(d)) { + if (collected) { + const DeviceOutput *output = device.GetDeviceOutput(image, m); + metadata.Process(output); + adu_histogram[experiment.GetFirstModuleOfDataStream(d) + m]->Add(*output); + transformation.ProcessModule(output, d); + } else + transformation.FillNotCollectedModule(m, d); } - images_to_compress.Put(slot); + if (collected) + device.FrameBufferRelease(image, m); } } - if (collected) - device.FrameBufferRelease(image, module_number); - } - } catch (...) { - SetError(std::current_exception()); - CancelCards(); - } -} -void FPGAImagePuller::CompressThread() { - while (const auto slot = images_to_compress.GetBlocking()) { - const int64_t image_number = slot->image_number; - try { DataMessage message{}; - message.number = image_number; - message.original_number = image_number; - slot->metadata->Export(message, expected_packets_per_image); + message.number = image; + message.original_number = image; + metadata.Export(message, expected_packets_per_image); + // No module of it came, or no room for it + if (drop || (message.image_collection_efficiency == 0.0f)) { + if (drop) + dropped_images++; + Emit(image, std::nullopt); + continue; + } // The card's spot finder and ROI map were not set up for this run; the receiver reports its own. message.strong_pixel_count.reset(); message.roi.clear(); - if (message.image_collection_efficiency == 0.0f) { // no module of it came - ReturnSlot(slot); - Emit(image_number, std::nullopt); - continue; - } - - // The compressed image goes to a buffer of the output's own, and the slot back at once: the slots are - // held only while an image is assembled and compressed, not while it waits for the receiver - const CompressedImage compressed = slot->transformation.GetCompressedImage(); + // The compressed image, copied once into a buffer of the output's own + const CompressedImage compressed = transformation.GetCompressedImage(); auto bytes = std::make_shared>(compressed.GetCompressed(), compressed.GetCompressed() + compressed.GetCompressedSize()); - ReturnSlot(slot); message.image = CompressedImage(bytes->data(), bytes->size(), compressed.GetWidth(), compressed.GetHeight(), compressed.GetMode(), compressed.GetCompressionAlgorithm()); @@ -313,42 +239,31 @@ void FPGAImagePuller::CompressThread() { output.cbor = std::make_shared(message); output.raw = std::shared_ptr(new ReceiveBufferRegion{bytes->data(), bytes->size()}, [bytes](ReceiveBufferRegion *region) { delete region; }); - Emit(image_number, std::move(output)); - } catch (...) { - SetError(std::current_exception()); - CancelCards(); - ReturnSlot(slot); - Emit(image_number, std::nullopt); + Emit(image, std::move(output)); } + } catch (...) { + SetError(std::current_exception()); + CancelCards(); } } // Whichever thread finishes the image next in line lets it, and those waiting behind it, out. void FPGAImagePuller::Emit(int64_t image_number, std::optional output) { - // The copies of the images let out here go only once order_mutex is released (the lock is declared after them, and - // `output` outlives both): the last copy of an image returns its slot, under images_mutex - std::vector released; std::unique_lock ul(order_mutex); - images_done.try_emplace(image_number, output); + images_done.try_emplace(image_number, std::move(output)); for (auto it = images_done.begin(); (it != images_done.end()) && (it->first == next_image); it = images_done.erase(it), next_image++) { if (it->second) { it->second->received = std::chrono::steady_clock::now(); - // The queue holds as many images as there are slots: blocking, the image waits for room; not - // blocking, it is dropped + // Blocking, the image waits for room; not blocking, it is dropped if (!(blocking ? PutWhileNotCancelled(*it->second) : outside_fifo.Put(*it->second))) dropped_images++; - released.push_back(std::move(*it->second)); } } } void FPGAImagePuller::FinalizeMeasurement() { - for (auto &f: module_futures) - f.get(); - for (size_t i = 0; i < compress_futures.size(); i++) - images_to_compress.Put(nullptr); - for (auto &f: compress_futures) + for (auto &f: image_futures) f.get(); CancelCards(); @@ -357,16 +272,16 @@ void FPGAImagePuller::FinalizeMeasurement() { // Only an error leaves images unfinished, holding back those behind them { - std::map> left; // destroyed after order_mutex, as in Emit std::unique_lock ul(order_mutex); for (auto &[n, output]: images_done) if (output && !PutWhileNotCancelled(*output)) dropped_images++; - left.swap(images_done); + images_done.clear(); } if (dropped_images > 0) - logger.Warning("FPGA image puller: {} images dropped, no free slot", dropped_images.load()); + logger.Warning("FPGA image puller: {} images dropped, the receiver's queue of {} images full", dropped_images.load(), + queue); EndMessage end{}; for (size_t i = 0; i < adu_histogram.size(); i++) @@ -377,8 +292,10 @@ void FPGAImagePuller::FinalizeMeasurement() { // Waits for room in the queue, as long as the receiver takes from it: after a cancel it no longer does bool FPGAImagePuller::PutWhileNotCancelled(const ImagePullerOutput &output) { - while (!outside_fifo.PutTimeout(output, std::chrono::milliseconds(100))) - if (cancelled) - return false; - return true; + const auto t0 = std::chrono::steady_clock::now(); + bool ret = true; + while (ret && !outside_fifo.PutTimeout(output, std::chrono::milliseconds(100))) + ret = !cancelled; + queue_wait_ns += std::chrono::duration_cast(std::chrono::steady_clock::now() - t0).count(); + return ret; } diff --git a/receiver/FPGAImagePuller.h b/receiver/FPGAImagePuller.h index f34d862f2..9a8bc31fb 100644 --- a/receiver/FPGAImagePuller.h +++ b/receiver/FPGAImagePuller.h @@ -4,7 +4,6 @@ #pragma once #include -#include #include #include #include @@ -20,84 +19,73 @@ #include "../image_puller/ImagePuller.h" #include "../jungfrau/JFCalibration.h" -// The images of a collection from the FPGA cards, as a detector stream: assembled and compressed here, in image order +// The images of a collection from the FPGA cards, as a detector stream, in image order. As JFJochReceiverFPGA: each +// thread takes the next image, waits for its modules in the cards' buffers, assembles them into an image of its own +// and compresses it; the image leaves as its compressed bytes, and the cards' buffers go back. The cards' buffers are +// the only window over the images in flight. class FPGAImagePuller : public ImagePuller { public: - static constexpr size_t DefaultSlots = 128; + // Images compressed and waiting for the receiver + static constexpr size_t DefaultQueue = 128; // A module this far behind the fastest one of its card is taken as missing from that frame, as the device itself - // does. Behind another card it is waited for as long as the slots can hold the images started meanwhile: the - // cards run on their own and one can be ahead, but past max_slots its images would be dropped anyway. + // does. Behind another card it is waited for until that card is `queue` images ahead (not blocking). static constexpr int64_t MissingAfterFrames = AcquisitionCounters::ThresholdFramesLost + 2; private: - struct Slot { - explicit Slot(const DiffractionExperiment &experiment) : transformation(experiment) { - transformation.ReserveCompressedBuffer(); - } - FrameTransformation transformation; - std::unique_ptr metadata; - std::atomic modules_left = 0; - int64_t image_number = 0; - }; - const DiffractionExperiment experiment; // What the cards run: the experiment, or with dummy modules (CardExperiment) const DiffractionExperiment card_experiment; Logger &logger; AcquisitionDeviceGroup &devices; - const size_t max_slots; - // Blocking: an image waits for a free slot instead of being dropped, and no module is given up for being behind - // the others, so the cards hold their frames and stall at the source. + const size_t queue; + // Blocking: an image waits for room in the queue instead of being dropped, and no module is given up for being + // behind the others, so the cards keep their frames and stall at the source. const bool blocking; const double frame_rate_hz; // images taken from the cards at most at this rate (0: as they come) std::chrono::steady_clock::time_point start_time; - std::condition_variable slot_returned; - std::atomic slot_wait_ns = 0; + std::atomic queue_wait_ns = 0; uint64_t expected_packets_per_image = 0; - std::mutex images_mutex; - std::vector> free_slots; - std::map> images_in_progress; - std::vector image_dropped; + std::atomic next_to_take = 0; std::atomic dropped_images = 0; + // Frames given up on that may still arrive, by card and module: their buffers go back once they do + std::mutex given_up_mutex; + std::vector>> given_up; + void ReleaseLateFrames(uint16_t data_stream, uint16_t module_number); + // What is done, waiting for the images before it. No value: that image will not come. std::mutex order_mutex; std::map> images_done; int64_t next_image = 0; - ThreadSafeFIFO> images_to_compress; std::vector> adu_histogram; std::mutex error_mutex; std::exception_ptr error; std::atomic failed = false; // a failed card may never report finished: nothing waits for it then - std::atomic cancelled = false; // Cancel(): no image waits for a slot any more + std::atomic cancelled = false; // Cancel(): no image waits for the receiver any more void SetError(std::exception_ptr e); std::vector> acquire_futures; - std::vector> module_futures; - std::vector> compress_futures; + std::vector> image_futures; std::future finish_future; std::once_flag finish_once; void AcquireThread(uint16_t data_stream, const PixelMask &mask, const JFCalibration *calibration, std::latch &ready); - void ModuleThread(uint16_t data_stream, uint16_t module_number); - void CompressThread(); + void ImageThread(); void FinalizeMeasurement(); - void WaitForFrame(uint16_t data_stream, uint16_t module_number, int64_t frame, int64_t &oldest_held); + // False where the frame is given up on + bool WaitForFrame(uint16_t data_stream, uint16_t module_number, int64_t frame); int64_t FastestFrame() const; - int64_t LastFrame() const; - std::shared_ptr GetSlot(int64_t image_number); - void ReturnSlot(const std::shared_ptr &slot); void Emit(int64_t image_number, std::optional output); bool PutWhileNotCancelled(const ImagePullerOutput &output); void CancelCards(); public: // Arms the cards; when it returns the detector can be started. FPGAImagePuller(const DiffractionExperiment &experiment, const PixelMask &mask, const JFCalibration *calibration, - AcquisitionDeviceGroup &devices, Logger &logger, int64_t compression_threads, - size_t max_slots = DefaultSlots, bool blocking = false, double frame_rate_hz = 0, + AcquisitionDeviceGroup &devices, Logger &logger, int64_t image_threads, + size_t queue = DefaultQueue, bool blocking = false, double frame_rate_hz = 0, int64_t modules_per_card = 0); // The experiment the cards run where each carries modules_per_card modules (0: as `x` splits them): each card's @@ -110,8 +98,8 @@ public: void Disconnect() override {} size_t GetDroppedImages() const override { return dropped_images; } bool IsBlocking() const override { return blocking; } - // Time the module threads waited for a free slot, summed over them - double GetSlotWaitTime_s() const { return static_cast(slot_wait_ns) * 1e-9; } + // Time the image threads waited for room in the queue, summed over them + double GetQueueWaitTime_s() const { return static_cast(queue_wait_ns) * 1e-9; } // The collection is over, whatever the cards have got: what is on its way still comes, then the end message. void Cancel(); diff --git a/receiver/JFJochReceiverService.cpp b/receiver/JFJochReceiverService.cpp index 988171da7..50d9d892d 100644 --- a/receiver/JFJochReceiverService.cpp +++ b/receiver/JFJochReceiverService.cpp @@ -40,13 +40,13 @@ JFJochReceiverService &JFJochReceiverService::RugnuxLive(bool enable, std::share return *this; } -JFJochReceiverService &JFJochReceiverService::FPGAImagePullerSettings(size_t slots, bool blocking, double frame_rate_hz, +JFJochReceiverService &JFJochReceiverService::FPGAImagePullerSettings(size_t queue, bool blocking, double frame_rate_hz, bool always, int64_t modules_per_card) { std::unique_lock ul_state(state_mutex); if (state != ReceiverState::Idle) throw JFJochException(JFJochExceptionCategory::WrongDAQState, "Cannot change the receiver path during data collection"); - fpga_image_puller_slots = slots; + fpga_image_puller_queue = queue; fpga_image_puller_blocking = blocking; fpga_image_puller_rate_hz = frame_rate_hz; fpga_image_puller_always = always; @@ -54,9 +54,9 @@ JFJochReceiverService &JFJochReceiverService::FPGAImagePullerSettings(size_t slo return *this; } -double JFJochReceiverService::GetFPGAImagePullerSlotWaitTime_s() const { +double JFJochReceiverService::GetFPGAImagePullerQueueWaitTime_s() const { std::unique_lock ul(state_mutex); - return fpga_puller ? fpga_puller->GetSlotWaitTime_s() : 0.0; + return fpga_puller ? fpga_puller->GetQueueWaitTime_s() : 0.0; } // A PSI collection analysed by rugnux live; summation on the host needs JFJochReceiverFPGA @@ -146,7 +146,7 @@ void JFJochReceiverService::Start(const DiffractionExperiment &experiment, // A PSI detector's frames through FPGAImagePuller go to the stream receivers, as a DECTRIS stream does if (FPGAImagePullerFor(experiment)) { fpga_puller = std::make_shared(experiment, pixel_mask, calibration, aq_devices, logger, - nthreads, fpga_image_puller_slots, + nthreads, fpga_image_puller_queue, fpga_image_puller_blocking, fpga_image_puller_rate_hz, fpga_image_puller_modules_per_card); puller = fpga_puller; diff --git a/receiver/JFJochReceiverService.h b/receiver/JFJochReceiverService.h index 3ac3cbed2..86672a0c0 100644 --- a/receiver/JFJochReceiverService.h +++ b/receiver/JFJochReceiverService.h @@ -44,7 +44,7 @@ class JFJochReceiverService { // A PSI collection analysed by rugnux live goes through FPGAImagePuller to the stream receivers bool fpga_image_puller_always = false; int64_t fpga_image_puller_modules_per_card = 0; - size_t fpga_image_puller_slots = FPGAImagePuller::DefaultSlots; + size_t fpga_image_puller_queue = FPGAImagePuller::DefaultQueue; bool fpga_image_puller_blocking = false; double fpga_image_puller_rate_hz = 0; std::shared_ptr fpga_puller; @@ -77,14 +77,14 @@ public: int64_t stills_downsample = 1); RugnuxLiveSnapshot GetRugnuxStatus() const; void ClearRugnuxStatus(); // back to Idle, as before any collection - // slots, blocking, frame_rate_hz, modules_per_card: see FPGAImagePuller. always: every PSI collection but pedestal + // queue, blocking, frame_rate_hz, modules_per_card: see FPGAImagePuller. always: every PSI collection but pedestal // and host summation through the puller, without rugnux to JFJochReceiverLite (for tests comparing it with // JFJochReceiverFPGA) - JFJochReceiverService& FPGAImagePullerSettings(size_t slots = FPGAImagePuller::DefaultSlots, bool blocking = false, + JFJochReceiverService& FPGAImagePullerSettings(size_t queue = FPGAImagePuller::DefaultQueue, bool blocking = false, double frame_rate_hz = 0, bool always = false, int64_t modules_per_card = 0); - // Of the last collection through FPGAImagePuller: FPGAImagePuller::GetSlotWaitTime_s, 0 without one - double GetFPGAImagePullerSlotWaitTime_s() const; + // Of the last collection through FPGAImagePuller: FPGAImagePuller::GetQueueWaitTime_s, 0 without one + double GetFPGAImagePullerQueueWaitTime_s() const; JFJochReceiverService& PreviewSocket(const std::string &addr, const std::optional &watermark = {}); JFJochReceiverService& MetadataSocket(const std::string &addr); diff --git a/tests/FPGAImagePullerTest.cpp b/tests/FPGAImagePullerTest.cpp index 178248b91..35bee6f41 100644 --- a/tests/FPGAImagePullerTest.cpp +++ b/tests/FPGAImagePullerTest.cpp @@ -166,7 +166,7 @@ namespace { JFJochReceiverService service(devices, logger, pusher, 256); service.NumThreads(4); service.SetSpotFindingSettings(Spots()); - service.FPGAImagePullerSettings(FPGAImagePuller::DefaultSlots, false, 0, puller); + service.FPGAImagePullerSettings(FPGAImagePuller::DefaultQueue, false, 0, puller); service.RugnuxLive(rugnux, nullptr, 2, 30); PixelMask mask(x); @@ -420,7 +420,7 @@ TEST_CASE("FPGAImagePuller_SameAsFPGA_EIGER_32bit", "[FPGAImagePuller]") { CollectingPusher pusher; JFJochReceiverService service(devices, logger, pusher, 256); service.NumThreads(4).SetSpotFindingSettings(Spots()); - service.FPGAImagePullerSettings(FPGAImagePuller::DefaultSlots, false, 0, puller); + service.FPGAImagePullerSettings(FPGAImagePuller::DefaultQueue, false, 0, puller); PixelMask mask(x); service.Start(x, mask, nullptr); const auto out = service.Stop(); @@ -495,7 +495,7 @@ TEST_CASE("FPGAImagePuller_SlowConsumer_Blocking", "[FPGAImagePuller]") { CHECK(end); puller.Stop(); CHECK(puller.GetDroppedImages() == 0); - CHECK(puller.GetSlotWaitTime_s() > 0.5); + CHECK(puller.GetQueueWaitTime_s() > 0.5); REQUIRE(numbers.size() == 20); for (size_t i = 0; i < numbers.size(); i++) CHECK(numbers[i] == static_cast(i)); @@ -716,7 +716,7 @@ TEST_CASE("FPGAImagePuller_Cancel", "[FPGAImagePuller]") { CollectingPusher pusher; JFJochReceiverService service(devices, logger, pusher, 256); service.NumThreads(2).SetSpotFindingSettings(Spots()); - service.FPGAImagePullerSettings(FPGAImagePuller::DefaultSlots, false, 0, true); + service.FPGAImagePullerSettings(FPGAImagePuller::DefaultQueue, false, 0, true); PixelMask mask(x); const JFCalibration calib = Calibration(x); service.Start(x, mask, &calib); @@ -751,7 +751,7 @@ TEST_CASE("FPGAImagePuller_NotForPedestalAndHostSummation", "[FPGAImagePuller]") CollectingPusher pusher; JFJochReceiverService service(devices, logger, pusher, 256); service.NumThreads(4).SetSpotFindingSettings(Spots()); - service.FPGAImagePullerSettings(FPGAImagePuller::DefaultSlots, false, 0, true); + service.FPGAImagePullerSettings(FPGAImagePuller::DefaultQueue, false, 0, true); PixelMask mask(x); const JFCalibration calib = Calibration(x); service.Start(x, mask, &calib); @@ -922,7 +922,7 @@ TEST_CASE("FPGAImagePuller_Writer", "[FPGAImagePuller]") { HDF5FilePusher pusher; JFJochReceiverService service(devices, logger, pusher, 256); service.NumThreads(2).SetSpotFindingSettings(Spots()); - service.FPGAImagePullerSettings(FPGAImagePuller::DefaultSlots, false, 0, true); + service.FPGAImagePullerSettings(FPGAImagePuller::DefaultQueue, false, 0, true); PixelMask mask(x); const JFCalibration calib = Calibration(x); service.Start(x, mask, &calib); diff --git a/tools/jfjoch_fpga_stills_test.cpp b/tools/jfjoch_fpga_stills_test.cpp index 38cf67851..4fd6a8282 100644 --- a/tools/jfjoch_fpga_stills_test.cpp +++ b/tools/jfjoch_fpga_stills_test.cpp @@ -42,7 +42,7 @@ void print_usage(Logger &logger) { logger.Info(" -t Indexing thread pool size (default: 8, as offline rugnux on stills; the broker's default is 4)"); logger.Info(" -r Rates the source is paced at, one collection each (default: 0 = as fast as it goes); the"); logger.Info(" host takes frame i no earlier than i/rate, the card waits meanwhile: blocking runs only"); - logger.Info(" -p FPGAImagePuller slots (default 128)"); + logger.Info(" -p Images FPGAImagePuller keeps compressed for the receiver (default 128)"); logger.Info(" -U No dummy modules: where the cards carry different numbers of modules, they run apart"); logger.Info(" -k Analyse 1 of every images on average (rugnux live stills_downsample, default 1)"); logger.Info(" -d Not blocking, as the broker runs: images the host has no room for are dropped. The cards'"); @@ -92,7 +92,7 @@ int64_t GeneratorImages(AcquisitionDeviceGroup &aq_devices, const DiffractionExp // A stored dataset through the card and rugnux live stills; returns false where the run failed bool RunDataset(Logger &logger, AcquisitionDeviceGroup &aq_devices, const std::string &file, std::optional nimages, uint16_t nstreams, uint16_t nthreads, size_t send_buffer_size_MiB, - const IndexingSettings &indexing, const std::optional &cell, size_t puller_slots, + const IndexingSettings &indexing, const std::optional &cell, size_t puller_queue, const std::vector &rates, bool dropping, bool pad, bool verbose, int64_t downsample, const std::optional &space_group) { RegisterHDF5Filter(); @@ -195,9 +195,9 @@ bool RunDataset(Logger &logger, AcquisitionDeviceGroup &aq_devices, const std::s for (const double rate: rates) { // Blocking at source: the puller waits for a free slot and the receiver for room in the image buffer, // the cards hold their frames and their generators stall - service.FPGAImagePullerSettings(puller_slots, !dropping, rate, false, modules_per_card); + service.FPGAImagePullerSettings(puller_queue, !dropping, rate, false, modules_per_card); logger.Info(""); - logger.Info("=== FPGAImagePuller ({} slots, {}), {} ===", puller_slots, dropping ? "dropping" : "blocking", + logger.Info("=== FPGAImagePuller (queue {}, {}), {} ===", puller_queue, dropping ? "dropping" : "blocking", (rate > 0) ? fmt::format("source paced at {:.1f} Hz", rate) : std::string("source as fast as it goes")); rusage usage_start{}; @@ -251,7 +251,7 @@ bool RunDataset(Logger &logger, AcquisitionDeviceGroup &aq_devices, const std::s // threads waited for a free slot, as a fraction of that span (mean over the modules) const double delivery_s = live.last_image_s.value_or(0); const double delivered_hz = (delivery_s > 0) ? static_cast(output.status.images_collected - 1) / delivery_s : 0; - const double blocked = (delivery_s > 0) ? service.GetFPGAImagePullerSlotWaitTime_s() / (delivery_s * x.GetModulesNum()) : 0; + const double blocked = (delivery_s > 0) ? service.GetFPGAImagePullerQueueWaitTime_s() / delivery_s : 0; logger.Info("Images expected {} collected {} sent {} dropped {} efficiency {:.4f}", x.GetImageNum(), output.status.images_collected, output.status.images_sent, @@ -325,7 +325,7 @@ int main(int argc, char **argv) { std::optional cell; IndexingAlgorithmEnum indexing = IndexingAlgorithmEnum::Auto; uint16_t indexing_threads = 8; // as offline rugnux's stills (Rugnux::StillsIndexerThreads) - size_t puller_slots = FPGAImagePuller::DefaultSlots; + size_t puller_queue = FPGAImagePuller::DefaultQueue; std::optional mock_card_MiB; bool verbose = false; std::vector rates = {0}; @@ -383,7 +383,7 @@ int main(int argc, char **argv) { break; } case 'p': - puller_slots = atol(optarg); + puller_queue = atol(optarg); break; case 'd': dropping = true; @@ -445,7 +445,7 @@ int main(int argc, char **argv) { bool ret = false; try { ret = RunDataset(logger, aq_devices, argv[optind], nimages, nstreams, nthreads, send_buffer_size_MiB, - i_settings, cell, puller_slots, rates, dropping, pad, verbose, downsample, space_group); + i_settings, cell, puller_queue, rates, dropping, pad, verbose, downsample, space_group); } catch (std::exception &e) { logger.Error(e.what()); } From deb4eee165060ffb758b60059e0449aa73ea07de Mon Sep 17 00:00:00 2001 From: Filip Leonarski Date: Wed, 18 Nov 2026 16:35:50 +0100 Subject: [PATCH 27/41] docs/JFJOCH_BROKER.md: the FPGA rugnux path - Lite for a rotation the buffer cannot hold, no calibration in the file Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01UqXYdHHZ4cogS1mrGUtfN7 --- docs/JFJOCH_BROKER.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/JFJOCH_BROKER.md b/docs/JFJOCH_BROKER.md index d13c178c8..b1c77b14d 100644 --- a/docs/JFJOCH_BROKER.md +++ b/docs/JFJOCH_BROKER.md @@ -222,7 +222,7 @@ goniometer and the rugnux live setting: |---|---|---|---| | FPGA cards (PSI JUNGFRAU, PSI EIGER) | pedestal run | `JFJochReceiverPedestal` | the raw frames into the pedestal and its RMS; nothing on any stream | | FPGA cards | rugnux live off, or summation on the host | `JFJochReceiverFPGA` | the card's converted pixels, spots, azimuthal and ROI sums into the image; summation on the host above what the card sums; indexing of each image; the calibration to the writer | -| FPGA cards | rugnux live on | `FPGAImagePuller`, then `JFJochReceiverRugnuxRotation` or `JFJochReceiverRugnuxStills` | the cards' frames assembled and compressed on the host into a stream as a DECTRIS detector gives, then taken as the DECTRIS rows below | +| FPGA cards | rugnux live on | `FPGAImagePuller`, then `JFJochReceiverRugnuxRotation` or `JFJochReceiverRugnuxStills` (`JFJochReceiverLite` for a rotation run the image buffer cannot hold) | the cards' frames assembled and compressed on the host into a stream as a DECTRIS detector gives, then taken as the DECTRIS rows below; the pedestal and gain calibration is not written to the file on this path | | DECTRIS stream | dark-mask sequence | `JFJochReceiverDarkMask` | the dark frames into the mask; nothing on any stream | | DECTRIS stream | rugnux live off, or a rotation run the image buffer cannot hold | `JFJochReceiverLite` | each image on the GPU: masking, azimuthal and ROI integration, spot finding, indexing | | DECTRIS stream | rugnux live on, rotation that fits the image buffer | `JFJochReceiverRugnuxRotation` | images forwarded as they come; rugnux reads the collection back from the image buffer and runs the whole pipeline | From 4c9cc48382bad97db2e05bac5197db6ff19de1e6 Mon Sep 17 00:00:00 2001 From: Filip Leonarski Date: Wed, 18 Nov 2026 17:10:32 +0100 Subject: [PATCH 28/41] Live stills hold: frames in a slot of their own in a quarter of the image buffer, seen while they wait 38137e16a packed every waiting frame into the hold, so a frame was no longer in the image buffer by its number until analysed (JFJochReceiverRugnux_Stills_ ImagesVisibleDuringPrePass failed). The waiting half of the image buffer is now split: up to a quarter of the slots hold a frame each, serialised there as before (the image routes find it), the rest of the half packs frames as their compressed bytes (HoldArena). The bound is unchanged: at most half of the image buffer, nothing beside it. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01UqXYdHHZ4cogS1mrGUtfN7 --- docs/JFJOCH_BROKER.md | 7 +-- receiver/JFJochReceiverRugnuxStills.cpp | 67 ++++++++++++++++++++----- receiver/JFJochReceiverRugnuxStills.h | 9 ++-- 3 files changed, 65 insertions(+), 18 deletions(-) diff --git a/docs/JFJOCH_BROKER.md b/docs/JFJOCH_BROKER.md index b1c77b14d..43e3b31f4 100644 --- a/docs/JFJOCH_BROKER.md +++ b/docs/JFJOCH_BROKER.md @@ -373,9 +373,10 @@ of its frames indexed, as with a small image buffer, a low hit rate or a chip wh cell given), the distance in the header is used for the whole run: this is a warning in the log and a note of the live status, and a wrong header distance then costs resolution and indexed frames. -Frames arriving during the pre-pass, or faster than the analysis, wait in the image buffer as their compressed bytes, -packed into at most half of its slots (several frames to a slot); the other half is for the analysed frames, which go -to the writer from a slot each, with one slot kept per analysis thread. The receiver's image memory is the image +Frames arriving during the pre-pass, or faster than the analysis, wait in at most half of the image buffer: a quarter +of its slots hold a frame each (it can be seen through the image routes while it waits), the rest of that half +holds frames as their compressed bytes, several to a slot; the other half is for the analysed frames, which go to +the writer from a slot each, with one slot kept per analysis thread. The receiver's image memory is the image buffer (`image_buffer_MiB`, `-B` of `jfjoch_fpga_stills_test`) and nothing beside it. A frame that finds the waiting half full is dropped and counted as for a full image buffer, so analysis slower than the frame rate costs frames, not memory. Where the writer lags behind, the analysis diff --git a/receiver/JFJochReceiverRugnuxStills.cpp b/receiver/JFJochReceiverRugnuxStills.cpp index 82dc8c559..809e0b64d 100644 --- a/receiver/JFJochReceiverRugnuxStills.cpp +++ b/receiver/JFJochReceiverRugnuxStills.cpp @@ -54,8 +54,10 @@ void JFJochReceiverRugnuxStills::OnStart(std::chrono::steady_clock::time_point r const int64_t slots = image_buffer.GetStatus().total_slots; // The frames that wait take at most half of the image buffer; the other half is for those analysed, sent from // a slot each, and a slot is kept free for each analysis thread to send with - const int64_t keep_free = std::min(stills_nthreads, slots / 2); - hold_arena = std::make_unique(image_buffer, slots / 2, keep_free, experiment.GetImageBufferLocationSize()); + stills_keep_free = std::min(stills_nthreads, slots / 2); + visible_max = slots / 4; + hold_arena = std::make_unique(image_buffer, slots / 2 - visible_max, stills_keep_free, + experiment.GetImageBufferLocationSize()); const StartMessage start = MakeStartMessage(experiment, pixel_mask, *az_int_mapping); // The frames are shown from their arrival, on the stated geometry until the pre-pass has decided its own. // To the image buffer only: the writer and the ZeroMQ streams get the one start message, after the pre-pass. @@ -90,26 +92,67 @@ void JFJochReceiverRugnuxStills::OnImage(uint32_t id, DataMessage &message, std: CountImage(message); const size_t size = message.image.GetCompressedSize(); - // Waits for the analysis as its compressed bytes, packed into slots of the image buffer (HoldArena) + // Waits for the analysis in half of the image buffer at most: in a slot of its own, where it can be seen while it + // waits (it is not sent from there), in up to half of those slots; else as its compressed bytes, packed with + // others into the rest (HoldArena) auto held = std::make_shared(); - HoldArena::Region region = hold_arena->Allocate(size); - while (!region.data && image_puller.IsBlocking() && !cancelled) { - std::this_thread::sleep_for(std::chrono::milliseconds(1)); + HoldArena::Region region; + const auto hold = [&] { + if (visible_held.fetch_add(1) < visible_max) { + held->slot = image_buffer.GetImageSlot(stills_keep_free); + if (held->slot) { + held->release = [this] { --visible_held; }; + return true; + } + } + --visible_held; region = hold_arena->Allocate(size); + return region.data != nullptr; + }; + bool held_ok = hold(); + while (!held_ok && image_puller.IsBlocking() && !cancelled) { + std::this_thread::sleep_for(std::chrono::milliseconds(1)); + held_ok = hold(); } - if (!region.data) { + if (!held_ok) { writer_queue_full = true; return; } - memcpy(region.data, message.image.GetCompressed(), size); - held->release = std::move(region.release); // Not chosen (stills_downsample): written as it came, without its analysis held->analyse = StillsImageSelected(message.number, downsample, StillsGPUAnalysis::PREPASS_MAX_IMAGES); held->message = message; StampImage(held->message, image_puller.GetCurrentFifoUtilization()); - held->message.image = CompressedImage(region.data, size, message.image.GetWidth(), message.image.GetHeight(), - message.image.GetMode(), message.image.GetCompressionAlgorithm(), - message.image.GetChannel()); + + if (held->slot) { + // In the slot as an image without analysis; the analysis reads the image where it is in the slot. + auto slot_buffer = static_cast(held->slot->GetImage()); + CBORStream2Serializer serializer(slot_buffer, experiment.GetImageBufferLocationSize()); + held->message.image = CompressedImage(nullptr, 0, message.image.GetWidth(), message.image.GetHeight(), + message.image.GetMode(), message.image.GetCompressionAlgorithm(), + message.image.GetChannel()); + serializer.SerializeImage(held->message); + const size_t image_offset = serializer.GetImageAppendOffset(); + if (image_offset + size + 32 >= static_cast(experiment.GetImageBufferLocationSize())) { + logger.Error("Dropping image {} - metadata {} B + image {} B do not fit in buffer slot {} B", message.number, + image_offset, size, experiment.GetImageBufferLocationSize()); + return; + } + memcpy(slot_buffer + image_offset, message.image.GetCompressed(), size); + serializer.AppendImage(size); + held->message.image = CompressedImage(slot_buffer + image_offset, size, message.image.GetWidth(), + message.image.GetHeight(), message.image.GetMode(), + message.image.GetCompressionAlgorithm(), message.image.GetChannel()); + held->slot->SetImageNumber(message.number); + held->slot->SetImageSize(serializer.GetBufferSize()); + held->slot->SetIndexed(false); + held->slot->ReadyToSend(); + } else { + memcpy(region.data, message.image.GetCompressed(), size); + held->release = std::move(region.release); + held->message.image = CompressedImage(region.data, size, message.image.GetWidth(), message.image.GetHeight(), + message.image.GetMode(), message.image.GetCompressionAlgorithm(), + message.image.GetChannel()); + } stills->Hold(held); } diff --git a/receiver/JFJochReceiverRugnuxStills.h b/receiver/JFJochReceiverRugnuxStills.h index 7227e2fe4..57d5c09ee 100644 --- a/receiver/JFJochReceiverRugnuxStills.h +++ b/receiver/JFJochReceiverRugnuxStills.h @@ -22,9 +22,12 @@ class JFJochReceiverRugnuxStills : public JFJochReceiverStream, public StillsSin IndexerThreadPool *const indexing_thread_pool; const int64_t stills_nthreads; - // The frames waiting for the analysis, packed as their compressed bytes into at most half of the image - // buffer's slots: a frame is a fraction of a slot (1.5 MB of a 24 MB slot on a 9M detector), and the pre-pass - // holds every frame that arrives before it is over + // The frames waiting for the analysis take at most half of the image buffer's slots: a quarter as a slot each, + // the rest packed as their compressed bytes (a frame is a fraction of a slot: 1.5 MB of a 24 MB slot on a 9M + // detector, and the pre-pass holds every frame that arrives before it is over) + int64_t stills_keep_free = 0; // slots frames do not take, for the analysis threads to send with + int64_t visible_max = 0; + std::atomic visible_held = 0; std::unique_ptr hold_arena; std::mutex stills_mutex; From c1ddc1abb47c19e78f96d71244d3320211f104c6 Mon Sep 17 00:00:00 2001 From: Filip Leonarski Date: Wed, 18 Nov 2026 17:25:26 +0100 Subject: [PATCH 29/41] OpenAPI image_time_us: say where summation runs, drop the 256 * frame_time maximum The text said the image time is at most 256 frame times. Nothing enforces that: summation of 2..255 frames runs on the FPGA (IsCPUSummation, MAX_FPGA_SUMMATION), and anything longer is summed on the host by JFJochReceiverFPGA, which takes no rugnux live analysis (FPGAImagePullerFor). The description now says so. Text only; C++ model comment, frontend client and python client docs regenerated. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01UqXYdHHZ4cogS1mrGUtfN7 --- broker/gen/model/Dataset_settings.h | 2 +- broker/jfjoch_api.yaml | 3 ++- docs/python_client/docs/DatasetSettings.md | 2 +- frontend/src/client/types.gen.ts | 6 ++++-- 4 files changed, 8 insertions(+), 5 deletions(-) diff --git a/broker/gen/model/Dataset_settings.h b/broker/gen/model/Dataset_settings.h index 5c9a220e5..ba91eefb2 100644 --- a/broker/gen/model/Dataset_settings.h +++ b/broker/gen/model/Dataset_settings.h @@ -81,7 +81,7 @@ public: bool ntriggerIsSet() const; void unsetNtrigger(); /// - /// Image time. If not provided (or zero value) the frame time is assumed as default. For JUNGFRAU image time must be multiple of frame time and max value is 256 * frame_time. In XFEL mode: summation happens for frames collected with multiple triggers. Ignored for storage cells and if raw data are saved. + /// Image time. If not provided (or zero value) the frame time is assumed as default. For JUNGFRAU image time must be multiple of frame time. Up to 255 frames are summed on the FPGA; a longer image time is summed on the host, which is slower and runs no rugnux live analysis. In XFEL mode: summation happens for frames collected with multiple triggers. Ignored for storage cells and if raw data are saved. /// int64_t getImageTimeUs() const; void setImageTimeUs(int64_t const value); diff --git a/broker/jfjoch_api.yaml b/broker/jfjoch_api.yaml index 8157bb7e4..5abb78447 100644 --- a/broker/jfjoch_api.yaml +++ b/broker/jfjoch_api.yaml @@ -409,7 +409,8 @@ components: description: | Image time. If not provided (or zero value) the frame time is assumed as default. - For JUNGFRAU image time must be multiple of frame time and max value is 256 * frame_time. + For JUNGFRAU image time must be multiple of frame time. Up to 255 frames are summed on the FPGA; + a longer image time is summed on the host, which is slower and runs no rugnux live analysis. In XFEL mode: summation happens for frames collected with multiple triggers. Ignored for storage cells and if raw data are saved. beam_x_pxl: diff --git a/docs/python_client/docs/DatasetSettings.md b/docs/python_client/docs/DatasetSettings.md index 27869f1dc..9e1e77451 100644 --- a/docs/python_client/docs/DatasetSettings.md +++ b/docs/python_client/docs/DatasetSettings.md @@ -7,7 +7,7 @@ Name | Type | Description | Notes ------------ | ------------- | ------------- | ------------- **images_per_trigger** | **int** | For standard synchrotron data collection - this is number of images collected per one TTL trigger For XFEL (pulsed source) - this number is ignored and set to 1 For storage cell mode - this number is ignored and set to number of storage cells | [optional] [default to 1] **ntrigger** | **int** | Number of TTL trigger that the detector is expected to receive during data collection | [optional] [default to 1] -**image_time_us** | **int** | Image time. If not provided (or zero value) the frame time is assumed as default. For JUNGFRAU image time must be multiple of frame time and max value is 256 * frame_time. In XFEL mode: summation happens for frames collected with multiple triggers. Ignored for storage cells and if raw data are saved. | [optional] +**image_time_us** | **int** | Image time. If not provided (or zero value) the frame time is assumed as default. For JUNGFRAU image time must be multiple of frame time. Up to 255 frames are summed on the FPGA; a longer image time is summed on the host, which is slower and runs no rugnux live analysis. In XFEL mode: summation happens for frames collected with multiple triggers. Ignored for storage cells and if raw data are saved. | [optional] **beam_x_pxl** | **float** | /entry/detector/beam_center_x in NXmx Beam center in X direction [pixels] | **beam_y_pxl** | **float** | /entry/detector/beam_center_y in NXmx Beam center in X direction [pixels] | **detector_distance_mm** | **float** | /entry/detector/distance in NXmx Detector distance [mm] | diff --git a/frontend/src/client/types.gen.ts b/frontend/src/client/types.gen.ts index 049d8cfe9..0473e22cc 100644 --- a/frontend/src/client/types.gen.ts +++ b/frontend/src/client/types.gen.ts @@ -166,7 +166,8 @@ export type dataset_settings = { /** * Image time. * If not provided (or zero value) the frame time is assumed as default. - * For JUNGFRAU image time must be multiple of frame time and max value is 256 * frame_time. + * For JUNGFRAU image time must be multiple of frame time. Up to 255 frames are summed on the FPGA; + * a longer image time is summed on the host, which is slower and runs no rugnux live analysis. * In XFEL mode: summation happens for frames collected with multiple triggers. * Ignored for storage cells and if raw data are saved. * @@ -2641,7 +2642,8 @@ export type dataset_settingsWritable = { /** * Image time. * If not provided (or zero value) the frame time is assumed as default. - * For JUNGFRAU image time must be multiple of frame time and max value is 256 * frame_time. + * For JUNGFRAU image time must be multiple of frame time. Up to 255 frames are summed on the FPGA; + * a longer image time is summed on the host, which is slower and runs no rugnux live analysis. * In XFEL mode: summation happens for frames collected with multiple triggers. * Ignored for storage cells and if raw data are saved. * From d8f41a488f6b658bb932e4d093d8efc8b5c2b939 Mon Sep 17 00:00:00 2001 From: Filip Leonarski Date: Wed, 18 Nov 2026 18:49:54 +0100 Subject: [PATCH 30/41] Card summation of 128 frames or more: packets of a module counted on the host The card counts the packets of a summed module in 16 bits (axis_completion packet_count, hls_jfjoch.h), 512 per frame, so from 128 summed frames the count wraps: at 128 and 256 to exactly 0, which the host took for a module not collected (IsAnyPacketCollected), so every image was lost; between them the efficiency came out wrong. Where 512 * card summation exceeds 16 bits, the host now counts the packets from the module's packet mask (the packets present in all of its frames) times the summation, and keeps the count in 32 bits (Completion, AcquisitionCounters). Exact for complete modules; with packets lost in some frames it counts only those present in all. The mock of the card keeps the card's 16-bit count, so it shows the same wrap (checked: without this, summation 256 on the mock delivers no image). Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01HVeDQrPqZ52Tp6rzzZGxf3 --- acquisition_device/AcquisitionCounters.cpp | 2 +- acquisition_device/AcquisitionCounters.h | 2 +- acquisition_device/AcquisitionDevice.cpp | 10 ++++++++++ acquisition_device/AcquisitionDevice.h | 1 + acquisition_device/Completion.h | 2 +- 5 files changed, 14 insertions(+), 3 deletions(-) diff --git a/acquisition_device/AcquisitionCounters.cpp b/acquisition_device/AcquisitionCounters.cpp index 966751706..9d1cb5d74 100644 --- a/acquisition_device/AcquisitionCounters.cpp +++ b/acquisition_device/AcquisitionCounters.cpp @@ -31,7 +31,7 @@ void AcquisitionCounters::Reset(const DiffractionExperiment &experiment, uint16_ curr_frame_number[i] = 0; handle_for_frame = std::vector(expected_frames * nmodules, HandleNotFound); - packets_collected = std::vector(expected_frames * nmodules); + packets_collected = std::vector(expected_frames * nmodules); packets_per_module = std::vector(nmodules); total_packets = 0; expected_packets_per_module = 512 * experiment.GetFPGASummation(); diff --git a/acquisition_device/AcquisitionCounters.h b/acquisition_device/AcquisitionCounters.h index 5e978bd4f..6cb53fe06 100644 --- a/acquisition_device/AcquisitionCounters.h +++ b/acquisition_device/AcquisitionCounters.h @@ -21,7 +21,7 @@ class AcquisitionCounters { mutable std::condition_variable_any data_updated; std::vector handle_for_frame; - std::vector packets_collected; + std::vector packets_collected; uint64_t total_packets; std::vector packets_per_module; diff --git a/acquisition_device/AcquisitionDevice.cpp b/acquisition_device/AcquisitionDevice.cpp index 7e2d070a3..ea823b719 100644 --- a/acquisition_device/AcquisitionDevice.cpp +++ b/acquisition_device/AcquisitionDevice.cpp @@ -1,6 +1,7 @@ // SPDX-FileCopyrightText: 2024 Filip Leonarski, Paul Scherrer Institute // SPDX-License-Identifier: GPL-3.0-only +#include #include #include #include @@ -54,6 +55,7 @@ void AcquisitionDevice::StartAction(const DiffractionExperiment &experiment, uin counters.Reset(experiment, data_stream); expected_frames = experiment.GetFrameNum() / experiment.GetFPGASummation(); + fpga_summation = experiment.GetFPGASummation(); // Ensure internal WR queue is empty work_request_queue.Clear(); @@ -92,6 +94,14 @@ void AcquisitionDevice::WaitForActionComplete() { } if (!skip_analysis) { + // The card counts the packets of a summed module in 16 bits, which wraps from 128 frames on (512 a frame): + // counted here from those present in all the frames + if (512 * fpga_summation > UINT16_MAX) { + uint32_t packets = 0; + for (const auto &mask: output->module_statistics.packet_mask) + packets += std::popcount(mask); + output->module_statistics.packet_count = packets * fpga_summation; + } c.module_number = output->module_statistics.module_number; c.packet_count = output->module_statistics.packet_count; c.frame_number = output->module_statistics.frame_number; diff --git a/acquisition_device/AcquisitionDevice.h b/acquisition_device/AcquisitionDevice.h index 95da29371..3763182d0 100644 --- a/acquisition_device/AcquisitionDevice.h +++ b/acquisition_device/AcquisitionDevice.h @@ -38,6 +38,7 @@ class AcquisitionDevice { std::chrono::time_point end_time; int64_t expected_frames; + int64_t fpga_summation = 1; virtual void Start(const DiffractionExperiment& experiment, uint32_t flags) = 0; virtual void Finalize() {}; // do clean-up after action is done diff --git a/acquisition_device/Completion.h b/acquisition_device/Completion.h index 200716ef0..47d6129c6 100644 --- a/acquisition_device/Completion.h +++ b/acquisition_device/Completion.h @@ -14,7 +14,7 @@ struct Completion { uint64_t frame_number; uint32_t handle; - uint16_t packet_count; + uint32_t packet_count; uint16_t data_collection_id; uint16_t module_number; }; From 4e8ccc2b60ac323fb579ecff8a232f4d7a90d3ef Mon Sep 17 00:00:00 2001 From: Filip Leonarski Date: Wed, 18 Nov 2026 18:49:54 +0100 Subject: [PATCH 31/41] Hybrid summation: the card sums the largest divisor up to 256, the host the rest; through FPGAImagePuller too For a summation of N frames the card sums d, the largest divisor of N not above 256 (GetFPGASummation; 256 itself is now summed on the card), and the host the N/d card images of each image (GetHostSummation): 1000 = 250 x 4, a prime above 256 = 1 x N. CPUSummation(true) still puts all of it on the host. The card writes 32-bit where it sums and the host adds to it. FPGAImagePuller now takes summation on the host, so rugnux live runs on such collections. Each image thread keeps one int32 module accumulator per module (ModuleSummation, saturating, error pixels carried, as JFJochReceiverFPGA and the HLS do), takes the card's images of its image in order, all modules of each before the next, adds each into the accumulator and returns the card's buffer; the summed modules then go into the thread's image as before. A module missing from any card image is missing from the image. The card's per-frame spots and ROI sums were already not read on this path; the module statistics are those of the first card image with error, saturated, packet counts and pixel sum added (ModuleSummation now adds the pixel sum too). Packets expected per image and the not-blocking give-up distance are in card images (x N/d). JFJochReceiverFPGA follows the same split (it has to: the card's summation is set by the experiment), summing N/d card images instead of N frames; its end-of-run expected packets no longer multiply the run's total by the summation a second time. OpenAPI image_time_us and the broker docs describe the split; C++ model, frontend client and python client docs regenerated. Tests: the divisor rule, and N = 256 (card only), 1000 (250 x 4) and 257 (host only) on the mock through both receivers, pixels against a sum done in the test with error and saturated pixels and a 32-bit overflow. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01HVeDQrPqZ52Tp6rzzZGxf3 --- broker/gen/model/Dataset_settings.h | 2 +- broker/jfjoch_api.yaml | 6 +- common/DiffractionExperiment.cpp | 21 ++- common/DiffractionExperiment.h | 5 + common/ModuleSummation.cpp | 8 + common/ModuleSummation.h | 2 + docs/JFJOCH_BROKER.md | 14 +- docs/python_client/docs/DatasetSettings.md | 2 +- frontend/src/client/types.gen.ts | 12 +- receiver/FPGAImagePuller.cpp | 65 ++++++-- receiver/FPGAImagePuller.h | 3 + receiver/JFJochReceiverFPGA.cpp | 16 +- receiver/JFJochReceiverService.cpp | 8 +- tests/CMakeLists.txt | 1 + tests/DiffractionExperimentTest.cpp | 36 +++- tests/FPGAImagePullerSummationTest.cpp | 181 +++++++++++++++++++++ tests/FPGAImagePullerTest.cpp | 6 +- 17 files changed, 331 insertions(+), 57 deletions(-) create mode 100644 tests/FPGAImagePullerSummationTest.cpp diff --git a/broker/gen/model/Dataset_settings.h b/broker/gen/model/Dataset_settings.h index ba91eefb2..a91c0d4a5 100644 --- a/broker/gen/model/Dataset_settings.h +++ b/broker/gen/model/Dataset_settings.h @@ -81,7 +81,7 @@ public: bool ntriggerIsSet() const; void unsetNtrigger(); /// - /// Image time. If not provided (or zero value) the frame time is assumed as default. For JUNGFRAU image time must be multiple of frame time. Up to 255 frames are summed on the FPGA; a longer image time is summed on the host, which is slower and runs no rugnux live analysis. In XFEL mode: summation happens for frames collected with multiple triggers. Ignored for storage cells and if raw data are saved. + /// Image time. If not provided (or zero value) the frame time is assumed as default. For JUNGFRAU image time must be multiple of frame time. Up to 256 frames are summed on the FPGA. Above that the FPGA sums the largest number of frames up to 256 that divides the frames of an image (250 of 1000) and the host adds up the rest; the more the host sums, the slower (a prime number of frames is summed on the host entirely). In XFEL mode: summation happens for frames collected with multiple triggers. Ignored for storage cells and if raw data are saved. /// int64_t getImageTimeUs() const; void setImageTimeUs(int64_t const value); diff --git a/broker/jfjoch_api.yaml b/broker/jfjoch_api.yaml index 5abb78447..fdd8e0095 100644 --- a/broker/jfjoch_api.yaml +++ b/broker/jfjoch_api.yaml @@ -409,8 +409,10 @@ components: description: | Image time. If not provided (or zero value) the frame time is assumed as default. - For JUNGFRAU image time must be multiple of frame time. Up to 255 frames are summed on the FPGA; - a longer image time is summed on the host, which is slower and runs no rugnux live analysis. + For JUNGFRAU image time must be multiple of frame time. Up to 256 frames are summed on the FPGA. + Above that the FPGA sums the largest number of frames up to 256 that divides the frames of an image + (250 of 1000) and the host adds up the rest; the more the host sums, the slower (a prime number of + frames is summed on the host entirely). In XFEL mode: summation happens for frames collected with multiple triggers. Ignored for storage cells and if raw data are saved. beam_x_pxl: diff --git a/common/DiffractionExperiment.cpp b/common/DiffractionExperiment.cpp index b4a20a48b..a653b3462 100644 --- a/common/DiffractionExperiment.cpp +++ b/common/DiffractionExperiment.cpp @@ -881,14 +881,23 @@ int64_t DiffractionExperiment::GetSummation() const { } int64_t DiffractionExperiment::GetFPGASummation() const { - if (IsCPUSummation()) + const int64_t n = GetSummation(); + if (cpu_summation) return 1; - return GetSummation(); + for (int64_t d = std::min(n, MAX_FPGA_SUMMATION); d > 1; d--) + if (n % d == 0) + return d; + return 1; +} + +int64_t DiffractionExperiment::GetHostSummation() const { + return GetSummation() / GetFPGASummation(); } int64_t DiffractionExperiment::GetByteDepthFPGA() const { + // Summed on the card as well: 32-bit, the host adds to it if (IsCPUSummation()) - return 2; + return (GetFPGASummation() > 1) ? 4 : 2; return GetByteDepthImage(); } @@ -1638,11 +1647,7 @@ DiffractionExperiment &DiffractionExperiment::ApplyPixelMask(bool input) { } bool DiffractionExperiment::IsCPUSummation() const { - if (summation == 1) - return false; - if (summation >= MAX_FPGA_SUMMATION) - return true; - return cpu_summation; + return GetHostSummation() > 1; } DiffractionExperiment & DiffractionExperiment::ElectronSource(bool input) { diff --git a/common/DiffractionExperiment.h b/common/DiffractionExperiment.h index c55444a93..197455730 100644 --- a/common/DiffractionExperiment.h +++ b/common/DiffractionExperiment.h @@ -357,7 +357,10 @@ public: std::optional GetSpaceGroupNumber() const; bool GetSaveCalibration() const; int64_t GetSummation() const; + // The card sums the largest divisor of the summation up to MAX_FPGA_SUMMATION, the host the card's images of + // one image: GetSummation() = GetFPGASummation() * GetHostSummation() int64_t GetFPGASummation() const; + int64_t GetHostSummation() const; std::string GetSampleName() const; float GetIncidentEnergy_keV() const; float GetWavelength_A() const; @@ -424,7 +427,9 @@ public: [[nodiscard]] bool IsMaskPixelsWithoutG0() const; [[nodiscard]] bool IsApplyPixelMask() const; + // All of the summation on the host (tests) DiffractionExperiment& CPUSummation(bool input); + // The host sums part of the image (GetHostSummation() > 1) [[nodiscard]] bool IsCPUSummation() const; [[nodiscard]] FileWriterFormat GetFileWriterFormat() const; diff --git a/common/ModuleSummation.cpp b/common/ModuleSummation.cpp index 50866ae77..b05310401 100644 --- a/common/ModuleSummation.cpp +++ b/common/ModuleSummation.cpp @@ -17,6 +17,13 @@ ModuleSummation::ModuleSummation(bool in_pixel_signed, uint32_t in_fpga_depth_by throw JFJochException(JFJochExceptionCategory::InputParameterInvalid, "FPGA byte depth can be only 1, 2 or 4"); output = std::make_unique(); + Clear(); +} + +void ModuleSummation::Clear() { + std::unique_lock ul(module_summation_mutex); + first = true; + is_empty = false; memset(output.get(), 0, sizeof(DeviceOutput)); } @@ -69,6 +76,7 @@ void ModuleSummation::AddFPGAOutput(const DeviceOutput &input, const std::option output->module_statistics.err_pixels += input.module_statistics.err_pixels; output->module_statistics.saturated_pixels += input.module_statistics.saturated_pixels; output->module_statistics.packet_count += input.module_statistics.packet_count; + output->module_statistics.pixel_sum += input.module_statistics.pixel_sum; } // The only function not handled is spot finding diff --git a/common/ModuleSummation.h b/common/ModuleSummation.h index 31d63b178..cf59a3ec3 100644 --- a/common/ModuleSummation.h +++ b/common/ModuleSummation.h @@ -23,6 +23,8 @@ public: void AddFPGAOutput(const DeviceOutput& input, const std::optional &in_fpga_depth_bytes = {}); void AddEmptyOutput(); + // Empty, for the next image + void Clear(); [[nodiscard]] const DeviceOutput& GetOutput() const; [[nodiscard]] DeviceOutput& GetOutput(); diff --git a/docs/JFJOCH_BROKER.md b/docs/JFJOCH_BROKER.md index 43e3b31f4..0bef59630 100644 --- a/docs/JFJOCH_BROKER.md +++ b/docs/JFJOCH_BROKER.md @@ -221,8 +221,8 @@ goniometer and the rugnux live setting: | Input | Run | Receiver | What it does | |---|---|---|---| | FPGA cards (PSI JUNGFRAU, PSI EIGER) | pedestal run | `JFJochReceiverPedestal` | the raw frames into the pedestal and its RMS; nothing on any stream | -| FPGA cards | rugnux live off, or summation on the host | `JFJochReceiverFPGA` | the card's converted pixels, spots, azimuthal and ROI sums into the image; summation on the host above what the card sums; indexing of each image; the calibration to the writer | -| FPGA cards | rugnux live on | `FPGAImagePuller`, then `JFJochReceiverRugnuxRotation` or `JFJochReceiverRugnuxStills` (`JFJochReceiverLite` for a rotation run the image buffer cannot hold) | the cards' frames assembled and compressed on the host into a stream as a DECTRIS detector gives, then taken as the DECTRIS rows below; the pedestal and gain calibration is not written to the file on this path | +| FPGA cards | rugnux live off | `JFJochReceiverFPGA` | the card's converted pixels, spots, azimuthal and ROI sums into the image; summation on the host above what the card sums; indexing of each image; the calibration to the writer | +| FPGA cards | rugnux live on | `FPGAImagePuller`, then `JFJochReceiverRugnuxRotation` or `JFJochReceiverRugnuxStills` (`JFJochReceiverLite` for a rotation run the image buffer cannot hold) | the cards' frames assembled (and summed above what the cards sum) and compressed on the host into a stream as a DECTRIS detector gives, then taken as the DECTRIS rows below; the pedestal and gain calibration is not written to the file on this path | | DECTRIS stream | dark-mask sequence | `JFJochReceiverDarkMask` | the dark frames into the mask; nothing on any stream | | DECTRIS stream | rugnux live off, or a rotation run the image buffer cannot hold | `JFJochReceiverLite` | each image on the GPU: masking, azimuthal and ROI integration, spot finding, indexing | | DECTRIS stream | rugnux live on, rotation that fits the image buffer | `JFJochReceiverRugnuxRotation` | images forwarded as they come; rugnux reads the collection back from the image buffer and runs the whole pipeline | @@ -236,13 +236,19 @@ built for earlier indexing settings are released when the settings change. `azim moves the azimuthal integration of the FPGA workflow from the card to the host, which a profile with more bins than the card holds needs. +A card sums up to 256 frames into an image. For more, it sums the largest number of frames up to 256 that divides +the frames of an image (250 of 1000) and the host adds up the card's images (4 of 250 each), in 32 bits, saturating; +a pixel in error or saturated in any of them is so in the sum, and a module missing from any of them is missing +from the image. A prime number of frames above 256 is summed on the host entirely, at the cost of reading every +frame. + ## Rugnux live mode With rugnux live mode on, collections from a DECTRIS detector are processed inside the broker while they arrive: rotation collections by rugnux, and serial (stills) collections on the GPU with the geometry and mask a rugnux pre-pass decided (see [Serial collections](#serial-collections-experimental) below). In the FPGA workflow -(PSI JUNGFRAU and EIGER) the frames reach the same receivers through `FPGAImagePuller`, rotation and serial alike; -with summation on the host the collection runs image by image, as with the mode off. It is off by default; the +(PSI JUNGFRAU and EIGER) the frames reach the same receivers through `FPGAImagePuller`, rotation and serial alike. +It is off by default; the configuration file switches it on with `"rugnux": {"enable": true, "reserved_cpus": 4}`, where `reserved_cpus` is the number of CPU threads left to the receiver and the image pusher. diff --git a/docs/python_client/docs/DatasetSettings.md b/docs/python_client/docs/DatasetSettings.md index 9e1e77451..ad29b5dd6 100644 --- a/docs/python_client/docs/DatasetSettings.md +++ b/docs/python_client/docs/DatasetSettings.md @@ -7,7 +7,7 @@ Name | Type | Description | Notes ------------ | ------------- | ------------- | ------------- **images_per_trigger** | **int** | For standard synchrotron data collection - this is number of images collected per one TTL trigger For XFEL (pulsed source) - this number is ignored and set to 1 For storage cell mode - this number is ignored and set to number of storage cells | [optional] [default to 1] **ntrigger** | **int** | Number of TTL trigger that the detector is expected to receive during data collection | [optional] [default to 1] -**image_time_us** | **int** | Image time. If not provided (or zero value) the frame time is assumed as default. For JUNGFRAU image time must be multiple of frame time. Up to 255 frames are summed on the FPGA; a longer image time is summed on the host, which is slower and runs no rugnux live analysis. In XFEL mode: summation happens for frames collected with multiple triggers. Ignored for storage cells and if raw data are saved. | [optional] +**image_time_us** | **int** | Image time. If not provided (or zero value) the frame time is assumed as default. For JUNGFRAU image time must be multiple of frame time. Up to 256 frames are summed on the FPGA. Above that the FPGA sums the largest number of frames up to 256 that divides the frames of an image (250 of 1000) and the host adds up the rest; the more the host sums, the slower (a prime number of frames is summed on the host entirely). In XFEL mode: summation happens for frames collected with multiple triggers. Ignored for storage cells and if raw data are saved. | [optional] **beam_x_pxl** | **float** | /entry/detector/beam_center_x in NXmx Beam center in X direction [pixels] | **beam_y_pxl** | **float** | /entry/detector/beam_center_y in NXmx Beam center in X direction [pixels] | **detector_distance_mm** | **float** | /entry/detector/distance in NXmx Detector distance [mm] | diff --git a/frontend/src/client/types.gen.ts b/frontend/src/client/types.gen.ts index 0473e22cc..757c8a5fe 100644 --- a/frontend/src/client/types.gen.ts +++ b/frontend/src/client/types.gen.ts @@ -166,8 +166,10 @@ export type dataset_settings = { /** * Image time. * If not provided (or zero value) the frame time is assumed as default. - * For JUNGFRAU image time must be multiple of frame time. Up to 255 frames are summed on the FPGA; - * a longer image time is summed on the host, which is slower and runs no rugnux live analysis. + * For JUNGFRAU image time must be multiple of frame time. Up to 256 frames are summed on the FPGA. + * Above that the FPGA sums the largest number of frames up to 256 that divides the frames of an image + * (250 of 1000) and the host adds up the rest; the more the host sums, the slower (a prime number of + * frames is summed on the host entirely). * In XFEL mode: summation happens for frames collected with multiple triggers. * Ignored for storage cells and if raw data are saved. * @@ -2642,8 +2644,10 @@ export type dataset_settingsWritable = { /** * Image time. * If not provided (or zero value) the frame time is assumed as default. - * For JUNGFRAU image time must be multiple of frame time. Up to 255 frames are summed on the FPGA; - * a longer image time is summed on the host, which is slower and runs no rugnux live analysis. + * For JUNGFRAU image time must be multiple of frame time. Up to 256 frames are summed on the FPGA. + * Above that the FPGA sums the largest number of frames up to 256 that divides the frames of an image + * (250 of 1000) and the host adds up the rest; the more the host sums, the slower (a prime number of + * frames is summed on the host entirely). * In XFEL mode: summation happens for frames collected with multiple triggers. * Ignored for storage cells and if raw data are saved. * diff --git a/receiver/FPGAImagePuller.cpp b/receiver/FPGAImagePuller.cpp index 948e02acb..7ec665024 100644 --- a/receiver/FPGAImagePuller.cpp +++ b/receiver/FPGAImagePuller.cpp @@ -18,7 +18,8 @@ FPGAImagePuller::FPGAImagePuller(const DiffractionExperiment &in_experiment, con devices(in_devices), queue(in_queue), blocking(in_blocking), - frame_rate_hz(in_frame_rate_hz) { + frame_rate_hz(in_frame_rate_hz), + host_summation(in_experiment.GetHostSummation()) { const int ndatastreams = experiment.GetDataStreamsNum(); if (devices.size() < ndatastreams) throw JFJochException(JFJochExceptionCategory::InputParameterInvalid, @@ -32,7 +33,7 @@ FPGAImagePuller::FPGAImagePuller(const DiffractionExperiment &in_experiment, con given_up[d].resize(card_experiment.GetModulesNum(d)); devices[d].PrepareAction(card_experiment); // Of the modules of the image, not the dummies - expected_packets_per_image += devices[d].Counters().GetExpectedPacketsPerImage() + expected_packets_per_image += devices[d].Counters().GetExpectedPacketsPerImage() * host_summation * experiment.GetModulesNum(d) / card_experiment.GetModulesNum(d); } @@ -171,7 +172,7 @@ bool FPGAImagePuller::WaitForFrame(uint16_t data_stream, uint16_t module_number, || counters.IsAcquisitionFinished() || failed) break; if (!blocking && ((static_cast(counters.GetFastestFrameNumber()) >= frame + 2 + MissingAfterFrames) - || (FastestFrame() >= frame + 2 + static_cast(queue)))) + || (FastestFrame() >= frame + 2 + static_cast(queue) * host_summation))) break; std::this_thread::sleep_for(std::chrono::milliseconds(1)); } @@ -185,6 +186,11 @@ bool FPGAImagePuller::WaitForFrame(uint16_t data_stream, uint16_t module_number, void FPGAImagePuller::ImageThread() { // One image of its own, assembled and compressed here FrameTransformation transformation(experiment); + // Summation on the host: the cards' images of one image added up, one module each, as in JFJochReceiverFPGA + std::vector> summation; + if (host_summation > 1) + for (int m = 0; m < experiment.GetModulesNum(); m++) + summation.emplace_back(std::make_unique(experiment)); try { for (int64_t image = next_to_take++; image < experiment.GetImageNum() && !failed; image = next_to_take++) { if (frame_rate_hz > 0) @@ -194,24 +200,47 @@ void FPGAImagePuller::ImageThread() { // Not blocking, an image the receiver has no room for is not assembled: its frames go back at once const bool drop = !blocking && (GetCurrentFifoUtilization() >= queue); ImageMetadata metadata(experiment); - for (int d = 0; d < experiment.GetDataStreamsNum(); d++) { - auto &device = devices[d]; - for (int m = 0; m < card_experiment.GetModulesNum(d); m++) { - const bool collected = WaitForFrame(d, m, image); - // A dummy module (CardExperiment): its frames only go back to the card - if (!drop && m < experiment.GetModulesNum(d)) { - if (collected) { - const DeviceOutput *output = device.GetDeviceOutput(image, m); - metadata.Process(output); - adu_histogram[experiment.GetFirstModuleOfDataStream(d) + m]->Add(*output); - transformation.ProcessModule(output, d); - } else - transformation.FillNotCollectedModule(m, d); + auto take_module = [&](const DeviceOutput *output, int d, int m) { + metadata.Process(output); + adu_histogram[experiment.GetFirstModuleOfDataStream(d) + m]->Add(*output); + transformation.ProcessModule(output, d); + }; + for (auto &s: summation) + s->Clear(); + // The card's images of this image in their order, all modules of each before the next, as they come + for (int64_t frame = image * host_summation; frame < (image + 1) * host_summation; frame++) { + for (int d = 0; d < experiment.GetDataStreamsNum(); d++) { + auto &device = devices[d]; + for (int m = 0; m < card_experiment.GetModulesNum(d); m++) { + const bool collected = WaitForFrame(d, m, frame); + // A dummy module (CardExperiment): its frames only go back to the card + if (!drop && m < experiment.GetModulesNum(d)) { + if (!summation.empty()) { + auto &s = *summation[experiment.GetFirstModuleOfDataStream(d) + m]; + if (collected) + s.AddFPGAOutput(*device.GetDeviceOutput(frame, m)); + else + s.AddEmptyOutput(); + } else if (collected) + take_module(device.GetDeviceOutput(frame, m), d, m); + else + transformation.FillNotCollectedModule(m, d); + } + if (collected) + device.FrameBufferRelease(frame, m); } - if (collected) - device.FrameBufferRelease(image, m); } } + // A module missing from any of the card's images is missing from the image + if (!drop && !summation.empty()) + for (int d = 0; d < experiment.GetDataStreamsNum(); d++) + for (int m = 0; m < experiment.GetModulesNum(d); m++) { + const auto &s = *summation[experiment.GetFirstModuleOfDataStream(d) + m]; + if (s.empty()) + transformation.FillNotCollectedModule(m, d); + else + take_module(&s.GetOutput(), d, m); + } DataMessage message{}; message.number = image; diff --git a/receiver/FPGAImagePuller.h b/receiver/FPGAImagePuller.h index 9a8bc31fb..da757a4e6 100644 --- a/receiver/FPGAImagePuller.h +++ b/receiver/FPGAImagePuller.h @@ -16,6 +16,7 @@ #include "ImageMetadata.h" #include "../acquisition_device/AcquisitionDeviceGroup.h" #include "../common/ADUHistogram.h" +#include "../common/ModuleSummation.h" #include "../image_puller/ImagePuller.h" #include "../jungfrau/JFCalibration.h" @@ -41,6 +42,8 @@ private: // behind the others, so the cards keep their frames and stall at the source. const bool blocking; const double frame_rate_hz; // images taken from the cards at most at this rate (0: as they come) + // The cards' images making one image, summed here (DiffractionExperiment::GetHostSummation) + const int64_t host_summation; std::chrono::steady_clock::time_point start_time; std::atomic queue_wait_ns = 0; uint64_t expected_packets_per_image = 0; diff --git a/receiver/JFJochReceiverFPGA.cpp b/receiver/JFJochReceiverFPGA.cpp index 09bc6d2a1..89ab51f90 100644 --- a/receiver/JFJochReceiverFPGA.cpp +++ b/receiver/JFJochReceiverFPGA.cpp @@ -77,7 +77,7 @@ JFJochReceiverFPGA::JFJochReceiverFPGA(const DiffractionExperiment &in_experimen } if (experiment.IsCPUSummation()) - expected_packets_per_image *= experiment.GetSummation(); + expected_packets_per_image *= experiment.GetHostSummation(); logger.Debug("Data acquisition devices ready"); @@ -177,9 +177,9 @@ void JFJochReceiverFPGA::SummationThread(uint16_t data_stream, uint32_t threadid, ModuleSummation &summation) { ModuleSummation local_summation(experiment); - int64_t starting_frame = image_number * experiment.GetSummation(); + int64_t starting_frame = image_number * experiment.GetHostSummation(); - for (int64_t i = threadid; i < experiment.GetSummation(); i += summation_nthreads) { + for (int64_t i = threadid; i < experiment.GetHostSummation(); i += summation_nthreads) { const int64_t frame = starting_frame + i; // Frame will be processed only if one already collects frame+2 @@ -229,7 +229,7 @@ void JFJochReceiverFPGA::FrameTransformationThread(uint32_t threadid) { try { int64_t expected_frame = image_number; if (experiment.IsCPUSummation()) - expected_frame *= experiment.GetSummation(); + expected_frame *= experiment.GetHostSummation(); logger.Debug("Frame transformation thread - trying to get image {}", expected_frame); // If data acquisition is finished and fastest frame for the first device is behind @@ -491,7 +491,7 @@ void JFJochReceiverFPGA::Cancel(const JFJochException &e) { float JFJochReceiverFPGA::GetProgress() const { int64_t frames = experiment.GetImageNum(); if (experiment.IsCPUSummation()) - frames *= experiment.GetSummation(); + frames *= experiment.GetHostSummation(); if (acquisition_device[0].Counters().IsAcquisitionFinished()) return 1.0; @@ -570,10 +570,8 @@ JFJochReceiverOutput JFJochReceiverFPGA::GetFinalStatistics() const { JFJochReceiverOutput ret = JFJochReceiver::GetFinalStatistics(); for (int d = 0; d < ndatastreams; d++) { for (int m = 0; m < acquisition_device[d].Counters().GetModuleNumber(); m++) { - if (experiment.IsCPUSummation()) - ret.expected_packets.push_back(acquisition_device[d].Counters().GetTotalExpectedPacketsPerModule() * experiment.GetSummation()); - else - ret.expected_packets.push_back(acquisition_device[d].Counters().GetTotalExpectedPacketsPerModule()); + // All the frames of the collection, whoever sums them + ret.expected_packets.push_back(acquisition_device[d].Counters().GetTotalExpectedPacketsPerModule()); ret.received_packets.push_back(acquisition_device[d].Counters().GetTotalPackets(m)); } } diff --git a/receiver/JFJochReceiverService.cpp b/receiver/JFJochReceiverService.cpp index 50d9d892d..251ded179 100644 --- a/receiver/JFJochReceiverService.cpp +++ b/receiver/JFJochReceiverService.cpp @@ -59,10 +59,10 @@ double JFJochReceiverService::GetFPGAImagePullerQueueWaitTime_s() const { return fpga_puller ? fpga_puller->GetQueueWaitTime_s() : 0.0; } -// A PSI collection analysed by rugnux live; summation on the host needs JFJochReceiverFPGA +// A PSI collection analysed by rugnux live bool JFJochReceiverService::FPGAImagePullerFor(const DiffractionExperiment &experiment) const { if ((experiment.GetDetectorType() == DetectorType::DECTRIS) || experiment.IsPedestalRun() - || experiment.IsCPUSummation() || (experiment.GetImageNum() <= 0)) + || (experiment.GetImageNum() <= 0)) return false; return fpga_image_puller_always || (rugnux_enable && (experiment.GetDetectorMode() == DetectorMode::Standard)); } @@ -157,10 +157,6 @@ void JFJochReceiverService::Start(const DiffractionExperiment &experiment, logger, spot_finding_settings, receiver_status, plots, image_buffer); } else if ((experiment.GetDetectorType() != DetectorType::DECTRIS) && !fpga_puller) { - if (rugnux_enable && experiment.IsCPUSummation()) { - analysis_warning = "no rugnux analysis: summation on the host"; - logger.Warning("{}", analysis_warning); - } // Summation on the host runs threads of its own for each image auto fpga_nthreads = nthreads; if (experiment.IsCPUSummation()) diff --git a/tests/CMakeLists.txt b/tests/CMakeLists.txt index 3ae22959c..d7b1cd12b 100644 --- a/tests/CMakeLists.txt +++ b/tests/CMakeLists.txt @@ -155,6 +155,7 @@ ADD_EXECUTABLE(jfjoch_test JFJochReceiverLiteTest.cpp JFJochReceiverRugnuxTest.cpp FPGAImagePullerTest.cpp + FPGAImagePullerSummationTest.cpp StillsSelectionTest.cpp HoldArenaTest.cpp GridScanSettingsTest.cpp diff --git a/tests/DiffractionExperimentTest.cpp b/tests/DiffractionExperimentTest.cpp index a5e2c172b..93c7090a0 100644 --- a/tests/DiffractionExperimentTest.cpp +++ b/tests/DiffractionExperimentTest.cpp @@ -783,10 +783,44 @@ TEST_CASE("DiffractionExperiment_Summation","[DiffractionExperiment]") { REQUIRE_NOTHROW(x.Summation(500)); CHECK(x.GetByteDepthImage() == 4); CHECK(x.GetSummation() == 500); - CHECK(x.GetFPGASummation() == 1); + CHECK(x.GetFPGASummation() == 250); + CHECK(x.GetHostSummation() == 2); CHECK(x.IsCPUSummation()); } +// The card sums the largest divisor up to 256, the host the rest +TEST_CASE("DiffractionExperiment_Summation_CardAndHost","[DiffractionExperiment]") { + DiffractionExperiment x; + for (const auto &[n, card]: std::vector>{ + {1, 1}, {7, 7}, {255, 255}, {256, 256}, {257, 1}, {512, 256}, {1000, 250}, {1024, 256}, {300, 150}, + {514, 2}, {1009, 1}}) { + INFO("summation " << n); + x.Summation(n); + CHECK(x.GetSummation() == n); + CHECK(x.GetFPGASummation() == card); + CHECK(x.GetHostSummation() == n / card); + CHECK(x.IsCPUSummation() == (card != n)); + } + + // 32-bit from the card where it sums as well; single frames at 16 bits + x.Summation(256); + CHECK(x.GetByteDepthFPGA() == 4); + x.Summation(1000); + CHECK(x.GetByteDepthFPGA() == 4); + CHECK(x.GetByteDepthImage() == 4); + x.Summation(257); + CHECK(x.GetByteDepthFPGA() == 2); + CHECK(x.GetByteDepthImage() == 4); + + // All of it on the host + x.Summation(7).CPUSummation(true); + CHECK(x.GetFPGASummation() == 1); + CHECK(x.GetHostSummation() == 7); + CHECK(x.IsCPUSummation()); + x.Summation(1); + CHECK(!x.IsCPUSummation()); +} + TEST_CASE("DiffractionExperiment_DetectorModuleHostname","[DiffractionExperiment]") { std::vector h = {"mx1", "mx2", "mx3"}; DiffractionExperiment x(DetectorSetup(DetectorGeometryModular(3), diff --git a/tests/FPGAImagePullerSummationTest.cpp b/tests/FPGAImagePullerSummationTest.cpp new file mode 100644 index 000000000..f8c8ef986 --- /dev/null +++ b/tests/FPGAImagePullerSummationTest.cpp @@ -0,0 +1,181 @@ +// SPDX-FileCopyrightText: 2026 Filip Leonarski, Paul Scherrer Institute +// SPDX-License-Identifier: GPL-3.0-only + +// Summation split between the card and the host, on the mock of the card: the card sums the largest divisor of the +// summation up to 256, the host the card's images of one image. The pixels of both receivers are checked against +// a sum done here. + +#include + +#include +#include + +#include "../frame_serialize/CBORStream2Deserializer.h" +#include "../image_pusher/ImagePusher.h" +#include "../receiver/FPGAImagePuller.h" +#include "../receiver/FrameTransformation.h" +#include "../receiver/JFJochReceiverService.h" +#include "MockCardOutput.h" + +namespace { + struct SumReceived { + DataMessage message; + std::vector pixels; + }; + + class SumPusher : public ImagePusher { + public: + std::mutex m; + std::map images; + + void StartDataCollection(StartMessage &) override {} + bool EndDataCollection(const EndMessage &) override { return true; } + bool SendCalibration(const CompressedImage &) override { return true; } + bool SendImage(const uint8_t *image_data, size_t image_size, int64_t image_number) override { + auto d = CBORStream2Deserialize(image_data, image_size); + SumReceived r; + r.message = d->data_message.value(); + r.message.image.GetUncompressed(r.pixels); + r.message.image = CompressedImage(); + std::unique_lock ul(m); + images.emplace(image_number, std::move(r)); + return true; + } + std::string PrintSetup() const override { return "summation"; } + ImagePusherType GetType() const override { return ImagePusherType::Test; } + }; + + DiffractionExperiment SumExperiment(int64_t summation, int64_t images) { + DiffractionExperiment x(DetJF(2)); + x.PedestalG0Frames(0).NumTriggers(1).UseInternalPacketGenerator(true).InternalPacketGeneratorImages(1) + .ImagesPerTrigger(images).ImagesPerFile(10).IncidentEnergy_keV(12.4) + .DetectorDistance_mm(75).BeamX_pxl(500).BeamY_pxl(600); + x.Conversion(); + x.Summation(summation).Compression(CompressionAlgorithm::BSHUF_LZ4); + return x; + } + + constexpr size_t ErrPixel = 100, SatPixel = 200, LargePixel = 300; + constexpr int64_t CardImageCount = 5; + + // What the card writes for its images, in its pixel format: a pattern, one pixel in error in the second image, one + // saturated in the third, and one large enough that three of them saturate in 32 bits + std::vector CardSums(const DiffractionExperiment &x) { + const bool wide = x.GetByteDepthFPGA() == 4; + std::vector ret; + std::vector values(RAW_MODULE_SIZE); + for (int64_t f = 0; f < CardImageCount; f++) { + CardImage image; + for (int m = 0; m < x.GetModulesNum(); m++) { + for (size_t i = 0; i < RAW_MODULE_SIZE; i++) + values[i] = (f * 7 + m * 3 + static_cast(i)) % 1000; + values[ErrPixel] = (f == 1) ? (wide ? INT32_MIN : INT16_MIN) : 5; + values[SatPixel] = (f == 2) ? (wide ? INT32_MAX : INT16_MAX) : 5; + values[LargePixel] = wide ? INT32_MAX / 3 + 1 : 30000; + auto output = std::make_unique(); + StorePixels(*output, x, values); + output->module_statistics.pixel_sum = 1000 * f + m; + image.push_back(std::move(output)); + } + ret.push_back(std::move(image)); + } + return ret; + } + + template + int32_t Pixel(const DeviceOutput &output, size_t i) { + return reinterpret_cast(output.pixels)[i]; + } + + // The image summed here from the card's images, by ModuleSummation's rule: an error in any is an error, then a + // saturated one or a sum reaching INT32_MAX is saturated. Assembled by FrameTransformation, as the receivers do. + std::vector Reference(const DiffractionExperiment &x, const std::vector &cards, int64_t image) { + const bool wide = x.GetByteDepthFPGA() == 4; + const int64_t err_src = wide ? INT32_MIN : INT16_MIN; + const int64_t sat_src = wide ? INT32_MAX : INT16_MAX; + const int64_t h = x.GetHostSummation(); + + FrameTransformation transformation(x); + for (int m = 0; m < x.GetModulesNum(); m++) { + auto output = std::make_unique(); + memset(output.get(), 0, sizeof(DeviceOutput)); + output->module_statistics.module_number = m; + auto sum = reinterpret_cast(output->pixels); + for (size_t i = 0; i < RAW_MODULE_SIZE; i++) { + int64_t acc = 0; + for (int64_t k = 0; k < h; k++) { + const auto &card = *cards[(image * h + k) % CardImageCount][m]; + const int64_t v = wide ? Pixel(card, i) : Pixel(card, i); + if (v == err_src || acc == INT32_MIN) + acc = INT32_MIN; + else if (v == sat_src || acc == INT32_MAX || acc + v >= INT32_MAX) + acc = INT32_MAX; + else + acc += v; + } + sum[i] = static_cast(acc); + } + transformation.ProcessModule(output.get(), 0); + } + auto p = static_cast(transformation.GetImage()); + return {p, p + x.GetPixelsNum() * x.GetByteDepthImage()}; + } + + std::map Run(const DiffractionExperiment &x, bool puller) { + auto devices = MockDevices(x, CardSums(x)); + Logger logger("FPGAImagePullerSummation"); + SumPusher pusher; + JFJochReceiverService service(devices, logger, pusher, 256); + SpotFindingSettings spots = DiffractionExperiment::DefaultDataProcessingSettings(); + spots.indexing = false; + service.NumThreads(4).SetSpotFindingSettings(spots); + service.FPGAImagePullerSettings(FPGAImagePuller::DefaultQueue, false, 0, puller); + PixelMask mask(x); + const JFCalibration calib = GeneratePedestalCalibration(x); + service.Start(x, mask, &calib); + const auto out = service.Stop(); + CHECK(out.efficiency == 1.0f); + CHECK(out.received_packets.empty() == puller); // only the FPGA receiver fills these + return std::move(pusher.images); + } + + void CheckSummation(int64_t summation, int64_t card, int64_t host) { + const auto x = SumExperiment(summation, 2); + REQUIRE(x.GetFPGASummation() == card); + REQUIRE(x.GetHostSummation() == host); + REQUIRE(x.GetByteDepthImage() == 4); + const auto cards = CardSums(x); + + for (const bool puller: {false, true}) { + INFO("puller " << puller); + const auto images = Run(x, puller); + REQUIRE(images.size() == 2); + for (const auto &[n, r]: images) { + INFO("image " << n); + CHECK(r.message.packets_received == r.message.packets_expected); + CHECK(r.message.packets_expected == 512 * summation * x.GetModulesNum()); + CHECK(r.pixels == Reference(x, cards, n)); + // From the card's module statistics: only the FPGA receiver keeps them + if (!puller) { + int64_t pixel_sum = 0; + for (int64_t k = 0; k < host; k++) + for (int m = 0; m < x.GetModulesNum(); m++) + pixel_sum += 1000 * ((n * host + k) % CardImageCount) + m; + CHECK(r.message.pixel_sum == pixel_sum); + } + } + } + } +} + +TEST_CASE("FPGAImagePuller_Summation256_CardOnly", "[FPGAImagePuller]") { + CheckSummation(256, 256, 1); +} + +TEST_CASE("FPGAImagePuller_Summation1000_Hybrid", "[FPGAImagePuller]") { + CheckSummation(1000, 250, 4); +} + +TEST_CASE("FPGAImagePuller_Summation257_HostOnly", "[FPGAImagePuller]") { + CheckSummation(257, 1, 257); +} diff --git a/tests/FPGAImagePullerTest.cpp b/tests/FPGAImagePullerTest.cpp index 35bee6f41..fee2d6f08 100644 --- a/tests/FPGAImagePullerTest.cpp +++ b/tests/FPGAImagePullerTest.cpp @@ -739,8 +739,8 @@ TEST_CASE("FPGAImagePuller_Cancel", "[FPGAImagePuller]") { } } -// Summation above the card's limit never takes the puller -TEST_CASE("FPGAImagePuller_NotForPedestalAndHostSummation", "[FPGAImagePuller]") { +// Summation on the host takes the puller as well +TEST_CASE("FPGAImagePuller_HostSummation", "[FPGAImagePuller]") { auto x = Base(DetJF(1), 2, 1); x.Conversion(); x.Summation(2).CPUSummation(true).Compression(CompressionAlgorithm::BSHUF_LZ4); @@ -757,7 +757,7 @@ TEST_CASE("FPGAImagePuller_NotForPedestalAndHostSummation", "[FPGAImagePuller]") service.Start(x, mask, &calib); const auto out = service.Stop(); CHECK(out.efficiency == 1.0f); - CHECK(!out.received_packets.empty()); // only the FPGA receiver fills these + CHECK(out.received_packets.empty()); // only the FPGA receiver fills these CHECK(out.status.images_collected == 2); } From 27c4306b7a924da7dacb6695efdadccca1729b30 Mon Sep 17 00:00:00 2001 From: Filip Leonarski Date: Wed, 18 Nov 2026 18:49:54 +0100 Subject: [PATCH 32/41] jfjoch_fpga_stills_test: -m sums frames into each image The card sums up to 256, above that the largest divisor up to 256 and the host the rest (hybrid summation); images are 32-bit. jfjoch_fpga_test already has -S for the card-only case. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01HVeDQrPqZ52Tp6rzzZGxf3 --- docs/TOOLS.md | 6 ++++-- tools/jfjoch_fpga_stills_test.cpp | 16 +++++++++++++--- 2 files changed, 17 insertions(+), 5 deletions(-) diff --git a/docs/TOOLS.md b/docs/TOOLS.md index bfb11fd86..c1baf283d 100644 --- a/docs/TOOLS.md +++ b/docs/TOOLS.md @@ -74,7 +74,7 @@ synthesis C model on the CPU, so no FPGA device is required. Measures rugnux live stills on the FPGA card(s), with a stored dataset standing in for the detector: ``` -jfjoch_fpga_stills_test [-i ] [-s ] [-N ] [-B ] [-C a,b,c,al,be,ga] [-X ] [-r ,...] [-p ] [-k ] [-d] [-v] [-K[]] +jfjoch_fpga_stills_test [-i ] [-s ] [-N ] [-B ] [-C a,b,c,al,be,ga] [-X ] [-r ,...] [-p ] [-k ] [-m ] [-d] [-v] [-K[]] ``` - The dataset must be a stored JUNGFRAU dataset with its modules assembled (1030 x 514 each, any placement @@ -89,7 +89,9 @@ jfjoch_fpga_stills_test [-i ] [-s ] [-N ] [-B ] [-C conversion off, so the card returns them verbatim; the host assembles them as signed 16-bit photon counts and rugnux live stills analyses them through `FPGAImagePuller`, as the broker does with rugnux live on (`-d`: not blocking, as the broker runs; `-v`: each card's progress every 0.5 s; `-k `: analyse 1 of every - F images on average, the rugnux live setting `stills_downsample`). Beam centre, distance, energy and the cell + F images on average, the rugnux live setting `stills_downsample`; `-m `: N frames summed into each image, by + the card up to 256 and above that the largest divisor of N up to 256 on the card and the rest on the host, 32-bit + images). Beam centre, distance, energy and the cell come from the file (`-C` overrides the cell; without one the frames are indexed de novo). Nothing is written. - Each card's generator holds module frames of its own modules only: as many images as its memory holds diff --git a/tools/jfjoch_fpga_stills_test.cpp b/tools/jfjoch_fpga_stills_test.cpp index 4fd6a8282..d33901c3d 100644 --- a/tools/jfjoch_fpga_stills_test.cpp +++ b/tools/jfjoch_fpga_stills_test.cpp @@ -45,6 +45,8 @@ void print_usage(Logger &logger) { logger.Info(" -p Images FPGAImagePuller keeps compressed for the receiver (default 128)"); logger.Info(" -U No dummy modules: where the cards carry different numbers of modules, they run apart"); logger.Info(" -k Analyse 1 of every images on average (rugnux live stills_downsample, default 1)"); + logger.Info(" -m Frames summed into an image (default 1): the card sums the largest divisor up to 256, the"); + logger.Info(" host the rest (1000 = 250 on the card x 4 on the host)"); logger.Info(" -d Not blocking, as the broker runs: images the host has no room for are dropped. The cards'"); logger.Info(" generators run free, each at a speed that goes with its modules: where the modules do not"); logger.Info(" divide evenly, each card is given dummy modules up to the largest count (-U: not)"); @@ -94,7 +96,7 @@ bool RunDataset(Logger &logger, AcquisitionDeviceGroup &aq_devices, const std::s std::optional nimages, uint16_t nstreams, uint16_t nthreads, size_t send_buffer_size_MiB, const IndexingSettings &indexing, const std::optional &cell, size_t puller_queue, const std::vector &rates, bool dropping, bool pad, bool verbose, int64_t downsample, - const std::optional &space_group) { + const std::optional &space_group, int64_t summation) { RegisterHDF5Filter(); JFJochHDF5Reader reader; reader.ReadFile(file); @@ -116,6 +118,9 @@ bool RunDataset(Logger &logger, AcquisitionDeviceGroup &aq_devices, const std::s .UseInternalPacketGenerator(true).DataStreams(nstreams); // The card returns the frames as loaded; the host assembles them as signed 16-bit photon counts x.JungfrauConvPhotonCnt(false).GeometryTransformation(true).PixelSigned(true).BitDepthImage(16); + // Summed: 32-bit images + if (summation > 1) + x.Summation(summation).BitDepthImage(32); x.Compression(CompressionAlgorithm::BSHUF_LZ4); x.IncidentEnergy_keV(file_x.GetIncidentEnergy_keV()).DetectorDistance_mm(file_x.GetDetectorDistance_mm()) .BeamX_pxl(file_x.GetBeamX_pxl()).BeamY_pxl(file_x.GetBeamY_pxl()); @@ -332,10 +337,11 @@ int main(int argc, char **argv) { bool dropping = false; bool pad = true; int64_t downsample = 1; + int64_t summation = 1; std::optional space_group; int opt; - while ((opt = getopt(argc, argv, "vi:s:N:B:C:S:X:t:r:p:dUk:K::")) != -1) { + while ((opt = getopt(argc, argv, "vi:s:N:B:C:S:X:t:r:p:dUk:m:K::")) != -1) { switch (opt) { case 'v': verbose = true; @@ -394,6 +400,9 @@ int main(int argc, char **argv) { case 'k': downsample = atol(optarg); break; + case 'm': + summation = atol(optarg); + break; case 'S': { const gemmi::SpaceGroup *sg = gemmi::find_spacegroup_by_name(optarg); if (sg == nullptr) { @@ -445,7 +454,8 @@ int main(int argc, char **argv) { bool ret = false; try { ret = RunDataset(logger, aq_devices, argv[optind], nimages, nstreams, nthreads, send_buffer_size_MiB, - i_settings, cell, puller_queue, rates, dropping, pad, verbose, downsample, space_group); + i_settings, cell, puller_queue, rates, dropping, pad, verbose, downsample, space_group, + summation); } catch (std::exception &e) { logger.Error(e.what()); } From b7771ca1d5c68a4718b5a2cad29c07ba321305a9 Mon Sep 17 00:00:00 2001 From: Filip Leonarski Date: Wed, 18 Nov 2026 19:00:54 +0100 Subject: [PATCH 33/41] summation_mode "hybrid" where the card and the host both sum The start message (and so the master file's detectorSpecific/summation_mode) says "fpga" where the card sums alone, "cpu" where the host sums alone (a prime above 256, or CPUSummation) and now "hybrid" where both do (1000 = 250 x 4). The string passes through CBOR and the writer as it is, and nothing reads it back into a decision, so files with "cpu" or "fpga" read as before. CBOR.md listed "internal", which the code never wrote: now none|fpga|cpu|hybrid. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01HVeDQrPqZ52Tp6rzzZGxf3 --- common/DiffractionExperiment.cpp | 12 ++++++------ docs/CBOR.md | 2 +- docs/HDF5.md | 2 +- docs/JFJOCH_BROKER.md | 2 +- tests/CBORTest.cpp | 15 +++++++++++++++ tests/DiffractionExperimentTest.cpp | 16 ++++++++++++++++ 6 files changed, 40 insertions(+), 9 deletions(-) diff --git a/common/DiffractionExperiment.cpp b/common/DiffractionExperiment.cpp index a653b3462..d025d79bf 100644 --- a/common/DiffractionExperiment.cpp +++ b/common/DiffractionExperiment.cpp @@ -799,12 +799,12 @@ void DiffractionExperiment::FillMessage(StartMessage &message) const { if (GetSummation() == 1) message.summation_mode = "none"; - else { - if (IsCPUSummation()) - message.summation_mode = "cpu"; - else - message.summation_mode = "fpga"; - } + else if (!IsCPUSummation()) + message.summation_mode = "fpga"; + else if (GetFPGASummation() > 1) + message.summation_mode = "hybrid"; + else + message.summation_mode = "cpu"; } float DiffractionExperiment::GetPixelSize_mm() const { diff --git a/docs/CBOR.md b/docs/CBOR.md index 52db9fc4b..b6abf765d 100644 --- a/docs/CBOR.md +++ b/docs/CBOR.md @@ -100,7 +100,7 @@ There are minor differences at the moment: | - attenuator_transmission | float | Attenuator transmission \[\] | | | - total_flux | float | Total flux \[ph/s\] | | | - space_group_number | uint64 | Space group number | | -| - summation_mode | string | Summation mode (internal\|fpga\|cpu) | | +| - summation_mode | string | Summation mode (none\|fpga\|cpu\|hybrid: the card and the host both sum) | | | - overwrite | bool | Overwrite existing HDF5 files | | | - file_format | int | File writer format: 0 = only data files, 1 = NXmx legacy external links, 2 = NXmx VDS, 3 = NXmx integrated, 4 = CBF (retired; rejected), 5 = TIFF (retired; rejected), 6 = no file written | | | - roi | Array(object) | ROI configurations; each has a `name` (the key of its `roi_integrals` entry and of `/entry/roi/` in HDF5) and is one of: | | diff --git a/docs/HDF5.md b/docs/HDF5.md index ddbc515dd..577c11a1b 100644 --- a/docs/HDF5.md +++ b/docs/HDF5.md @@ -595,7 +595,7 @@ one keep them only where every input has them. | Path | Class | Content | |------|-------|---------| -| `/entry/instrument/detector/detectorSpecific` | NXcollection | Dectris-style detector metadata + Jungfraujoch fields: `x_pixels_in_detector`, `y_pixels_in_detector`, `nimages`, `ntrigger`, `nimages_collected`, `nimages_written`, `data_collection_efficiency`, `max_receiver_delay`, `storage_cell_number`, `storage_cell_delay` [ns], `software_git_commit`, `software_git_date`, `jfjoch_release`, `jfjoch_writer_release`, `summation_mode`, `detect_ice_rings`, `gain_file_names`, `data_reduction_factor_serialmx`, `adu_histogram/` (`bin_width` and one vector per storage cell), `data_collection_efficiency_image`, `direct_beam_x`, `direct_beam_y`, `pixel_mask` (hard-linked as `/entry/instrument/detector/pixel_mask`), `storage_cell_image` (VDS, with storage cells) | +| `/entry/instrument/detector/detectorSpecific` | NXcollection | Dectris-style detector metadata + Jungfraujoch fields: `x_pixels_in_detector`, `y_pixels_in_detector`, `nimages`, `ntrigger`, `nimages_collected`, `nimages_written`, `data_collection_efficiency`, `max_receiver_delay`, `storage_cell_number`, `storage_cell_delay` [ns], `software_git_commit`, `software_git_date`, `jfjoch_release`, `jfjoch_writer_release`, `summation_mode` (`none`, `fpga`, `cpu` or `hybrid`: card and host both sum), `detect_ice_rings`, `gain_file_names`, `data_reduction_factor_serialmx`, `adu_histogram/` (`bin_width` and one vector per storage cell), `data_collection_efficiency_image`, `direct_beam_x`, `direct_beam_y`, `pixel_mask` (hard-linked as `/entry/instrument/detector/pixel_mask`), `storage_cell_image` (VDS, with storage cells) | | `/entry/instrument/detector/calibration` | NXcollection | per-channel pedestal / calibration images (bitshuffle-compressed) | | `/entry/instrument/fluorescence` | NXcollection | XRF spectrum: `energy` [eV], `data` | | `/entry/user` | NXcollection | scalar values supplied under `header_appendix.hdf5` | diff --git a/docs/JFJOCH_BROKER.md b/docs/JFJOCH_BROKER.md index 0bef59630..d34c50e19 100644 --- a/docs/JFJOCH_BROKER.md +++ b/docs/JFJOCH_BROKER.md @@ -240,7 +240,7 @@ A card sums up to 256 frames into an image. For more, it sums the largest number the frames of an image (250 of 1000) and the host adds up the card's images (4 of 250 each), in 32 bits, saturating; a pixel in error or saturated in any of them is so in the sum, and a module missing from any of them is missing from the image. A prime number of frames above 256 is summed on the host entirely, at the cost of reading every -frame. +frame. The start message and the master file's `summation_mode` say which: `fpga`, `hybrid` or `cpu`. ## Rugnux live mode diff --git a/tests/CBORTest.cpp b/tests/CBORTest.cpp index 5813c0e8e..648f9e800 100644 --- a/tests/CBORTest.cpp +++ b/tests/CBORTest.cpp @@ -283,6 +283,21 @@ TEST_CASE("CBORSerialize_Start_ThresholdEnergy", "[CBOR]") { REQUIRE(output_message.threshold_energy == message.threshold_energy); } +// The values the start message gives, and those of older files, pass as they are +TEST_CASE("CBORSerialize_Start_SummationMode", "[CBOR]") { + for (const std::string mode: {"none", "fpga", "cpu", "hybrid"}) { + std::vector buffer(8 * 1024 * 1024); + CBORStream2Serializer serializer(buffer.data(), buffer.size()); + StartMessage message{}; + message.summation_mode = mode; + REQUIRE_NOTHROW(serializer.SerializeSequenceStart(message)); + auto deserialized = CBORStream2Deserialize(buffer.data(), serializer.GetBufferSize()); + REQUIRE(deserialized); + REQUIRE(deserialized->start_message); + CHECK(deserialized->start_message->summation_mode == mode); + } +} + TEST_CASE("CBORSerialize_Start_Fluorescence", "[CBOR]") { std::vector buffer(8 * 1024 * 1024); CBORStream2Serializer serializer(buffer.data(), buffer.size()); diff --git a/tests/DiffractionExperimentTest.cpp b/tests/DiffractionExperimentTest.cpp index 93c7090a0..b03e87c77 100644 --- a/tests/DiffractionExperimentTest.cpp +++ b/tests/DiffractionExperimentTest.cpp @@ -821,6 +821,22 @@ TEST_CASE("DiffractionExperiment_Summation_CardAndHost","[DiffractionExperiment] CHECK(!x.IsCPUSummation()); } +// Who sums: the start message's summation_mode +TEST_CASE("DiffractionExperiment_SummationMode","[DiffractionExperiment]") { + DiffractionExperiment x; + StartMessage message; + for (const auto &[n, mode]: std::vector>{ + {1, "none"}, {7, "fpga"}, {256, "fpga"}, {1000, "hybrid"}, {514, "hybrid"}, {257, "cpu"}}) { + INFO("summation " << n); + x.Summation(n); + x.FillMessage(message); + CHECK(message.summation_mode == mode); + } + x.Summation(1000).CPUSummation(true); + x.FillMessage(message); + CHECK(message.summation_mode == "cpu"); +} + TEST_CASE("DiffractionExperiment_DetectorModuleHostname","[DiffractionExperiment]") { std::vector h = {"mx1", "mx2", "mx3"}; DiffractionExperiment x(DetectorSetup(DetectorGeometryModular(3), From 83fa6daa2f14af1d710b6a2d967070cedc84dd04 Mon Sep 17 00:00:00 2001 From: Filip Leonarski Date: Wed, 18 Nov 2026 19:53:42 +0100 Subject: [PATCH 34/41] FPGAImagePuller: one way through - no host stage discards an image Images now always wait for room in the queue to the receiver (128 compressed images, Queue), holding the cards' buffers, so the cards wait for host buffers and frames are lost only at the card, as the card's generator and a detector do. Removed what served only particular tests: the not-blocking path that dropped an image at a full queue (and the dropped count, which JFJochReceiverStream now reports as the base's 0), the host pacing of the source (frame_rate_hz), the queue-wait time, the queue size argument, the cross-card give-up (FastestFrame) with its late-frame bookkeeping (given_up, ReleaseLateFrames), and the dummy-module padding of the cards (CardExperiment, modules_per_card). The device itself gives up on a module lagging behind its card past ThresholdFramesLost and returns a frame that comes later; MissingAfterFrames stays beyond that, as the header says. FPGAImagePullerSettings is reduced to the one bool that sends every collection through the puller (tests comparing it with JFJochReceiverFPGA). IsBlocking() stays, now always true: JFJochReceiverRugnuxStills' hold waits on it, and that wait is changed on its own branch. The tests and jfjoch_fpga_stills_test are adapted in the commits that follow. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01HVeDQrPqZ52Tp6rzzZGxf3 --- image_puller/ImagePuller.h | 2 - receiver/FPGAImagePuller.cpp | 165 ++++++++--------------------- receiver/FPGAImagePuller.h | 55 +++------- receiver/JFJochReceiverService.cpp | 16 +-- receiver/JFJochReceiverService.h | 15 +-- receiver/JFJochReceiverStream.h | 1 - 6 files changed, 65 insertions(+), 189 deletions(-) diff --git a/image_puller/ImagePuller.h b/image_puller/ImagePuller.h index 4915bfbd7..5c9935730 100644 --- a/image_puller/ImagePuller.h +++ b/image_puller/ImagePuller.h @@ -76,8 +76,6 @@ public: virtual void Disconnect() = 0; - // Images the puller had no room for, which the receiver therefore never gets. - virtual size_t GetDroppedImages() const { return 0; } // The source waits for the receiver rather than lose an image: the receiver waits for room instead of dropping it virtual bool IsBlocking() const { return false; } }; diff --git a/receiver/FPGAImagePuller.cpp b/receiver/FPGAImagePuller.cpp index 7ec665024..5b0c1c791 100644 --- a/receiver/FPGAImagePuller.cpp +++ b/receiver/FPGAImagePuller.cpp @@ -9,16 +9,11 @@ FPGAImagePuller::FPGAImagePuller(const DiffractionExperiment &in_experiment, const PixelMask &mask, const JFCalibration *calibration, AcquisitionDeviceGroup &in_devices, - Logger &in_logger, int64_t image_threads, size_t in_queue, - bool in_blocking, double in_frame_rate_hz, int64_t modules_per_card) - : ImagePuller(in_queue + 2), // the images waiting, the start and the end message + Logger &in_logger, int64_t image_threads) + : ImagePuller(Queue + 2), // the images waiting, the start and the end message experiment(in_experiment), - card_experiment(CardExperiment(in_experiment, modules_per_card)), logger(in_logger), devices(in_devices), - queue(in_queue), - blocking(in_blocking), - frame_rate_hz(in_frame_rate_hz), host_summation(in_experiment.GetHostSummation()) { const int ndatastreams = experiment.GetDataStreamsNum(); if (devices.size() < ndatastreams) @@ -28,17 +23,12 @@ FPGAImagePuller::FPGAImagePuller(const DiffractionExperiment &in_experiment, con for (int m = 0; m < experiment.GetModulesNum(); m++) adu_histogram.emplace_back(std::make_unique()); - given_up.resize(ndatastreams); for (int d = 0; d < ndatastreams; d++) { - given_up[d].resize(card_experiment.GetModulesNum(d)); - devices[d].PrepareAction(card_experiment); - // Of the modules of the image, not the dummies - expected_packets_per_image += devices[d].Counters().GetExpectedPacketsPerImage() * host_summation - * experiment.GetModulesNum(d) / card_experiment.GetModulesNum(d); + devices[d].PrepareAction(experiment); + expected_packets_per_image += devices[d].Counters().GetExpectedPacketsPerImage() * host_summation; } - // The calibration and the mask are of the modules of the image - if ((experiment.GetDetectorType() != DetectorType::JUNGFRAU) || (modules_per_card > 0)) + if (experiment.GetDetectorType() != DetectorType::JUNGFRAU) calibration = nullptr; // The receiver's own start message is built from its experiment; this one only says the run has begun. @@ -47,7 +37,6 @@ FPGAImagePuller::FPGAImagePuller(const DiffractionExperiment &in_experiment, con outside_fifo.Put({.cbor = std::make_shared(start), .received = std::chrono::steady_clock::now()}); - start_time = std::chrono::steady_clock::now(); for (int i = 0; i < image_threads; i++) image_futures.emplace_back(std::async(std::launch::async, &FPGAImagePuller::ImageThread, this)); @@ -78,16 +67,6 @@ FPGAImagePuller::~FPGAImagePuller() { } } -DiffractionExperiment FPGAImagePuller::CardExperiment(const DiffractionExperiment &x, int64_t modules_per_card) { - if (modules_per_card <= 0) - return x; - DiffractionExperiment ret(x); - const DetectorSettings settings = x.GetDetectorSettings(); - ret.Detector(DetJF(static_cast(modules_per_card * x.GetDataStreamsNum()))); - ret.ImportDetectorSettings(settings); - return ret; -} - void FPGAImagePuller::SetError(std::exception_ptr e) { std::unique_lock ul(error_mutex); if (!error) @@ -95,17 +74,17 @@ void FPGAImagePuller::SetError(std::exception_ptr e) { failed = true; } -void FPGAImagePuller::Cancel() { - // An image waiting for room in the queue is dropped from here on: after a cancel the receiver takes no more images - cancelled = true; - CancelCards(); -} - -void FPGAImagePuller::CancelCards() { +void FPGAImagePuller::StopCards() { for (int d = 0; d < experiment.GetDataStreamsNum(); d++) devices[d].Cancel(); } +void FPGAImagePuller::Cancel() { + cancelled = true; + StopCards(); +} + +// Cancels first: a receiver that stopped on an error takes no more images, which would hold the threads otherwise void FPGAImagePuller::Stop() { Cancel(); std::call_once(finish_once, [this] { finish_future.get(); }); @@ -121,14 +100,11 @@ void FPGAImagePuller::AcquireThread(uint16_t data_stream, const PixelMask &mask, // Only what the card needs for the pixels: its analysis results are not read. if (calibration != nullptr) device.InitializeCalibration(experiment, *calibration); - if (card_experiment.GetModulesNum() == experiment.GetModulesNum()) - device.InitializePixelMask(experiment, mask); - else - device.InitializeEmptyPixelMask(card_experiment); - device.StartAction(card_experiment); + device.InitializePixelMask(experiment, mask); + device.StartAction(experiment); } catch (...) { SetError(std::current_exception()); - CancelCards(); // the image threads waiting on the other cards have to come out as well + StopCards(); // the image threads waiting on the other cards have to come out as well ready.count_down(); return; } @@ -138,49 +114,20 @@ void FPGAImagePuller::AcquireThread(uint16_t data_stream, const PixelMask &mask, device.WaitForActionComplete(); } catch (...) { SetError(std::current_exception()); - CancelCards(); + StopCards(); } } -int64_t FPGAImagePuller::FastestFrame() const { - int64_t ret = 0; - for (int d = 0; d < experiment.GetDataStreamsNum(); d++) - ret = std::max(ret, static_cast(devices[d].Counters().GetFastestFrameNumber())); - return ret; -} - -// The buffers of frames given up on that have come since go back to the card, which may need them for the frames -// waited for -void FPGAImagePuller::ReleaseLateFrames(uint16_t data_stream, uint16_t module_number) { - std::unique_lock ul(given_up_mutex); - auto &frames = given_up[data_stream][module_number]; - std::erase_if(frames, [&](int64_t f) { - if (!devices[data_stream].Counters().IsAnyPacketCollected(f, module_number)) - return false; - devices[data_stream].FrameBufferRelease(f, module_number); - return true; - }); -} - -// Polled: a dead card has to be noticed from the other cards' frames +// Polled: a dead card has to be noticed from the other cards' frames. A frame given up on that comes later is below +// the device's slowest frame then (MissingAfterFrames), and the device returns its buffer itself. bool FPGAImagePuller::WaitForFrame(uint16_t data_stream, uint16_t module_number, int64_t frame) { const auto &counters = devices[data_stream].Counters(); - while (true) { - ReleaseLateFrames(data_stream, module_number); - // A frame is complete once the module is two further on, as in JFJochReceiverFPGA - if ((static_cast(counters.GetCurrFrameNumber(module_number)) >= frame + 2) - || counters.IsAcquisitionFinished() || failed) - break; - if (!blocking && ((static_cast(counters.GetFastestFrameNumber()) >= frame + 2 + MissingAfterFrames) - || (FastestFrame() >= frame + 2 + static_cast(queue) * host_summation))) - break; + // A frame is complete once the module is two further on, as in JFJochReceiverFPGA + while ((static_cast(counters.GetCurrFrameNumber(module_number)) < frame + 2) + && !counters.IsAcquisitionFinished() && !failed + && (static_cast(counters.GetFastestFrameNumber()) < frame + 2 + MissingAfterFrames)) std::this_thread::sleep_for(std::chrono::milliseconds(1)); - } - if (counters.IsAnyPacketCollected(frame, module_number)) - return true; - std::unique_lock ul(given_up_mutex); - given_up[data_stream][module_number].push_back(frame); - return false; + return counters.IsAnyPacketCollected(frame, module_number); } void FPGAImagePuller::ImageThread() { @@ -193,12 +140,6 @@ void FPGAImagePuller::ImageThread() { summation.emplace_back(std::make_unique(experiment)); try { for (int64_t image = next_to_take++; image < experiment.GetImageNum() && !failed; image = next_to_take++) { - if (frame_rate_hz > 0) - std::this_thread::sleep_until(start_time + std::chrono::duration_cast( - std::chrono::duration(static_cast(image) / frame_rate_hz))); - - // Not blocking, an image the receiver has no room for is not assembled: its frames go back at once - const bool drop = !blocking && (GetCurrentFifoUtilization() >= queue); ImageMetadata metadata(experiment); auto take_module = [&](const DeviceOutput *output, int d, int m) { metadata.Process(output); @@ -211,28 +152,25 @@ void FPGAImagePuller::ImageThread() { for (int64_t frame = image * host_summation; frame < (image + 1) * host_summation; frame++) { for (int d = 0; d < experiment.GetDataStreamsNum(); d++) { auto &device = devices[d]; - for (int m = 0; m < card_experiment.GetModulesNum(d); m++) { + for (int m = 0; m < experiment.GetModulesNum(d); m++) { const bool collected = WaitForFrame(d, m, frame); - // A dummy module (CardExperiment): its frames only go back to the card - if (!drop && m < experiment.GetModulesNum(d)) { - if (!summation.empty()) { - auto &s = *summation[experiment.GetFirstModuleOfDataStream(d) + m]; - if (collected) - s.AddFPGAOutput(*device.GetDeviceOutput(frame, m)); - else - s.AddEmptyOutput(); - } else if (collected) - take_module(device.GetDeviceOutput(frame, m), d, m); + if (!summation.empty()) { + auto &s = *summation[experiment.GetFirstModuleOfDataStream(d) + m]; + if (collected) + s.AddFPGAOutput(*device.GetDeviceOutput(frame, m)); else - transformation.FillNotCollectedModule(m, d); - } + s.AddEmptyOutput(); + } else if (collected) + take_module(device.GetDeviceOutput(frame, m), d, m); + else + transformation.FillNotCollectedModule(m, d); if (collected) device.FrameBufferRelease(frame, m); } } } // A module missing from any of the card's images is missing from the image - if (!drop && !summation.empty()) + if (!summation.empty()) for (int d = 0; d < experiment.GetDataStreamsNum(); d++) for (int m = 0; m < experiment.GetModulesNum(d); m++) { const auto &s = *summation[experiment.GetFirstModuleOfDataStream(d) + m]; @@ -246,10 +184,8 @@ void FPGAImagePuller::ImageThread() { message.number = image; message.original_number = image; metadata.Export(message, expected_packets_per_image); - // No module of it came, or no room for it - if (drop || (message.image_collection_efficiency == 0.0f)) { - if (drop) - dropped_images++; + // No module of it came + if (message.image_collection_efficiency == 0.0f) { Emit(image, std::nullopt); continue; } @@ -272,7 +208,7 @@ void FPGAImagePuller::ImageThread() { } } catch (...) { SetError(std::current_exception()); - CancelCards(); + StopCards(); } } @@ -284,9 +220,7 @@ void FPGAImagePuller::Emit(int64_t image_number, std::optionalsecond) { it->second->received = std::chrono::steady_clock::now(); - // Blocking, the image waits for room; not blocking, it is dropped - if (!(blocking ? PutWhileNotCancelled(*it->second) : outside_fifo.Put(*it->second))) - dropped_images++; + Put(*it->second); } } } @@ -295,7 +229,7 @@ void FPGAImagePuller::FinalizeMeasurement() { for (auto &f: image_futures) f.get(); - CancelCards(); + StopCards(); for (auto &f: acquire_futures) f.get(); @@ -303,28 +237,17 @@ void FPGAImagePuller::FinalizeMeasurement() { { std::unique_lock ul(order_mutex); for (auto &[n, output]: images_done) - if (output && !PutWhileNotCancelled(*output)) - dropped_images++; + if (output) + Put(*output); images_done.clear(); } - if (dropped_images > 0) - logger.Warning("FPGA image puller: {} images dropped, the receiver's queue of {} images full", dropped_images.load(), - queue); - EndMessage end{}; for (size_t i = 0; i < adu_histogram.size(); i++) end.adu_histogram["module" + std::to_string(i)] = adu_histogram[i]->GetHistogram(); - PutWhileNotCancelled({.cbor = std::make_shared(end), - .received = std::chrono::steady_clock::now()}); + Put({.cbor = std::make_shared(end), .received = std::chrono::steady_clock::now()}); } -// Waits for room in the queue, as long as the receiver takes from it: after a cancel it no longer does -bool FPGAImagePuller::PutWhileNotCancelled(const ImagePullerOutput &output) { - const auto t0 = std::chrono::steady_clock::now(); - bool ret = true; - while (ret && !outside_fifo.PutTimeout(output, std::chrono::milliseconds(100))) - ret = !cancelled; - queue_wait_ns += std::chrono::duration_cast(std::chrono::steady_clock::now() - t0).count(); - return ret; +void FPGAImagePuller::Put(const ImagePullerOutput &output) { + while (!outside_fifo.PutTimeout(output, std::chrono::milliseconds(100)) && !cancelled); } diff --git a/receiver/FPGAImagePuller.h b/receiver/FPGAImagePuller.h index da757a4e6..e2d850644 100644 --- a/receiver/FPGAImagePuller.h +++ b/receiver/FPGAImagePuller.h @@ -23,38 +23,24 @@ // The images of a collection from the FPGA cards, as a detector stream, in image order. As JFJochReceiverFPGA: each // thread takes the next image, waits for its modules in the cards' buffers, assembles them into an image of its own // and compresses it; the image leaves as its compressed bytes, and the cards' buffers go back. The cards' buffers are -// the only window over the images in flight. +// the only window over the images in flight. No image is discarded here: an image waits for room in the queue to the +// receiver, holding the cards' buffers meanwhile, so the cards wait for the host. Images are lost only at the card. class FPGAImagePuller : public ImagePuller { public: // Images compressed and waiting for the receiver - static constexpr size_t DefaultQueue = 128; - // A module this far behind the fastest one of its card is taken as missing from that frame, as the device itself - // does. Behind another card it is waited for until that card is `queue` images ahead (not blocking). + static constexpr size_t Queue = 128; + // A module this far behind the fastest one of its card is taken as missing from that frame. It must stay beyond + // AcquisitionCounters::ThresholdFramesLost: the device then returns that frame's buffer itself if it comes later. static constexpr int64_t MissingAfterFrames = AcquisitionCounters::ThresholdFramesLost + 2; private: const DiffractionExperiment experiment; - // What the cards run: the experiment, or with dummy modules (CardExperiment) - const DiffractionExperiment card_experiment; Logger &logger; AcquisitionDeviceGroup &devices; - const size_t queue; - // Blocking: an image waits for room in the queue instead of being dropped, and no module is given up for being - // behind the others, so the cards keep their frames and stall at the source. - const bool blocking; - const double frame_rate_hz; // images taken from the cards at most at this rate (0: as they come) // The cards' images making one image, summed here (DiffractionExperiment::GetHostSummation) const int64_t host_summation; - std::chrono::steady_clock::time_point start_time; - std::atomic queue_wait_ns = 0; uint64_t expected_packets_per_image = 0; std::atomic next_to_take = 0; - std::atomic dropped_images = 0; - - // Frames given up on that may still arrive, by card and module: their buffers go back once they do - std::mutex given_up_mutex; - std::vector>> given_up; - void ReleaseLateFrames(uint16_t data_stream, uint16_t module_number); // What is done, waiting for the images before it. No value: that image will not come. std::mutex order_mutex; @@ -66,7 +52,7 @@ private: std::mutex error_mutex; std::exception_ptr error; std::atomic failed = false; // a failed card may never report finished: nothing waits for it then - std::atomic cancelled = false; // Cancel(): no image waits for the receiver any more + std::atomic cancelled = false; // Cancel(): the receiver takes no more images, nothing waits for it void SetError(std::exception_ptr e); std::vector> acquire_futures; @@ -78,34 +64,25 @@ private: void ImageThread(); void FinalizeMeasurement(); - // False where the frame is given up on + // False where the module is missing from the frame bool WaitForFrame(uint16_t data_stream, uint16_t module_number, int64_t frame); - int64_t FastestFrame() const; void Emit(int64_t image_number, std::optional output); - bool PutWhileNotCancelled(const ImagePullerOutput &output); - void CancelCards(); + // Waits for room in the queue, as long as the receiver takes from it: after a cancel it no longer does + void Put(const ImagePullerOutput &output); public: // Arms the cards; when it returns the detector can be started. FPGAImagePuller(const DiffractionExperiment &experiment, const PixelMask &mask, const JFCalibration *calibration, - AcquisitionDeviceGroup &devices, Logger &logger, int64_t image_threads, - size_t queue = DefaultQueue, bool blocking = false, double frame_rate_hz = 0, - int64_t modules_per_card = 0); - - // The experiment the cards run where each carries modules_per_card modules (0: as `x` splits them): each card's - // modules of `x` first, in their order, then dummy modules the generator sends and the puller does not read. - // For the internal generator, whose speed goes with the modules of the card: cards of different module counts - // run apart, where a detector's modules keep in step. - static DiffractionExperiment CardExperiment(const DiffractionExperiment &x, int64_t modules_per_card); + AcquisitionDeviceGroup &devices, Logger &logger, int64_t image_threads); ~FPGAImagePuller() override; void Disconnect() override {} - size_t GetDroppedImages() const override { return dropped_images; } - bool IsBlocking() const override { return blocking; } - // Time the image threads waited for room in the queue, summed over them - double GetQueueWaitTime_s() const { return static_cast(queue_wait_ns) * 1e-9; } + // Its images wait for the receiver, so the receiver's hold waits as well (JFJochReceiverRugnuxStills) + bool IsBlocking() const override { return true; } - // The collection is over, whatever the cards have got: what is on its way still comes, then the end message. + // The cards finish: what they have got still comes, then the end message. + void StopCards(); + // As StopCards(), and the receiver takes no more images: nothing waits for it any more. void Cancel(); - // After the receiver is done: stops the cards, waits for the threads, throws what went wrong with the cards. + // After the receiver is done: cancels, waits for the threads, throws what went wrong with the cards. void Stop(); }; diff --git a/receiver/JFJochReceiverService.cpp b/receiver/JFJochReceiverService.cpp index 251ded179..d7f44b31c 100644 --- a/receiver/JFJochReceiverService.cpp +++ b/receiver/JFJochReceiverService.cpp @@ -40,25 +40,15 @@ JFJochReceiverService &JFJochReceiverService::RugnuxLive(bool enable, std::share return *this; } -JFJochReceiverService &JFJochReceiverService::FPGAImagePullerSettings(size_t queue, bool blocking, double frame_rate_hz, - bool always, int64_t modules_per_card) { +JFJochReceiverService &JFJochReceiverService::FPGAImagePullerSettings(bool always) { std::unique_lock ul_state(state_mutex); if (state != ReceiverState::Idle) throw JFJochException(JFJochExceptionCategory::WrongDAQState, "Cannot change the receiver path during data collection"); - fpga_image_puller_queue = queue; - fpga_image_puller_blocking = blocking; - fpga_image_puller_rate_hz = frame_rate_hz; fpga_image_puller_always = always; - fpga_image_puller_modules_per_card = modules_per_card; return *this; } -double JFJochReceiverService::GetFPGAImagePullerQueueWaitTime_s() const { - std::unique_lock ul(state_mutex); - return fpga_puller ? fpga_puller->GetQueueWaitTime_s() : 0.0; -} - // A PSI collection analysed by rugnux live bool JFJochReceiverService::FPGAImagePullerFor(const DiffractionExperiment &experiment) const { if ((experiment.GetDetectorType() == DetectorType::DECTRIS) || experiment.IsPedestalRun() @@ -146,9 +136,7 @@ void JFJochReceiverService::Start(const DiffractionExperiment &experiment, // A PSI detector's frames through FPGAImagePuller go to the stream receivers, as a DECTRIS stream does if (FPGAImagePullerFor(experiment)) { fpga_puller = std::make_shared(experiment, pixel_mask, calibration, aq_devices, logger, - nthreads, fpga_image_puller_queue, - fpga_image_puller_blocking, fpga_image_puller_rate_hz, - fpga_image_puller_modules_per_card); + nthreads); puller = fpga_puller; } diff --git a/receiver/JFJochReceiverService.h b/receiver/JFJochReceiverService.h index 86672a0c0..361fd1e22 100644 --- a/receiver/JFJochReceiverService.h +++ b/receiver/JFJochReceiverService.h @@ -43,10 +43,6 @@ class JFJochReceiverService { // A PSI collection analysed by rugnux live goes through FPGAImagePuller to the stream receivers bool fpga_image_puller_always = false; - int64_t fpga_image_puller_modules_per_card = 0; - size_t fpga_image_puller_queue = FPGAImagePuller::DefaultQueue; - bool fpga_image_puller_blocking = false; - double fpga_image_puller_rate_hz = 0; std::shared_ptr fpga_puller; bool FPGAImagePullerFor(const DiffractionExperiment &experiment) const; @@ -77,14 +73,9 @@ public: int64_t stills_downsample = 1); RugnuxLiveSnapshot GetRugnuxStatus() const; void ClearRugnuxStatus(); // back to Idle, as before any collection - // queue, blocking, frame_rate_hz, modules_per_card: see FPGAImagePuller. always: every PSI collection but pedestal - // and host summation through the puller, without rugnux to JFJochReceiverLite (for tests comparing it with - // JFJochReceiverFPGA) - JFJochReceiverService& FPGAImagePullerSettings(size_t queue = FPGAImagePuller::DefaultQueue, bool blocking = false, - double frame_rate_hz = 0, bool always = false, - int64_t modules_per_card = 0); - // Of the last collection through FPGAImagePuller: FPGAImagePuller::GetQueueWaitTime_s, 0 without one - double GetFPGAImagePullerQueueWaitTime_s() const; + // Every PSI collection but a pedestal run through FPGAImagePuller, without rugnux to JFJochReceiverLite (for tests + // comparing it with JFJochReceiverFPGA) + JFJochReceiverService& FPGAImagePullerSettings(bool always); JFJochReceiverService& PreviewSocket(const std::string &addr, const std::optional &watermark = {}); JFJochReceiverService& MetadataSocket(const std::string &addr); diff --git a/receiver/JFJochReceiverStream.h b/receiver/JFJochReceiverStream.h index 7a4146b40..7749b08a8 100644 --- a/receiver/JFJochReceiverStream.h +++ b/receiver/JFJochReceiverStream.h @@ -57,7 +57,6 @@ protected: virtual void Cut(const std::string &reason) {} // the analysis that goes on after the images, if there is one void AddToEndMessage(EndMessage &message) override; - uint64_t GetImagesDropped() const override { return image_puller.GetDroppedImages(); } public: // Takes what the detector's start message decides into the experiment. static void ApplyStartMessage(DiffractionExperiment &experiment, const StartMessage &message); From 472759ee0bb37cd170b63c8f02efbf13c58766cd Mon Sep 17 00:00:00 2001 From: Filip Leonarski Date: Wed, 18 Nov 2026 19:53:42 +0100 Subject: [PATCH 35/41] FPGAImagePuller: a silent end stops the cards and still delivers what they have The broker ends every run with a silent cancel once the detector is done (JFJochServices -> JFJochReceiverService::Cancel(true)). With every image now waiting for the receiver, a full cancel there would cut the images still on their way. StopCards() stops the cards and lets what they hold through, then the end message; Cancel() is StopCards() plus "the receiver takes no more images". The service uses StopCards() for a silent cancel and Cancel() otherwise. Stop() still cancels first, for a receiver that ended on an error. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01HVeDQrPqZ52Tp6rzzZGxf3 --- receiver/JFJochReceiverService.cpp | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/receiver/JFJochReceiverService.cpp b/receiver/JFJochReceiverService.cpp index d7f44b31c..22beb46c2 100644 --- a/receiver/JFJochReceiverService.cpp +++ b/receiver/JFJochReceiverService.cpp @@ -241,7 +241,10 @@ void JFJochReceiverService::Cancel(bool silent) { std::unique_lock ul(state_mutex); if (state == ReceiverState::Running) { receiver->Cancel(silent); - if (fpga_puller) + // Silent: the detector has finished, and what the cards have got still goes to the receiver + if (fpga_puller && silent) + fpga_puller->StopCards(); + else if (fpga_puller) fpga_puller->Cancel(); } } From 0f2b89cb802e64f3757679e4fe54fc02de648dd9 Mon Sep 17 00:00:00 2001 From: Filip Leonarski Date: Wed, 18 Nov 2026 19:53:43 +0100 Subject: [PATCH 36/41] jfjoch_fpga_stills_test: one collection, as fast as it goes; docs say no host stage discards Removed -r (host pacing and the per-rate loop with its table), -d (the dropping run), -p (the queue size) and -U with the dummy-module padding; the blocked fraction, measured from the removed queue-wait time, is gone - the card's own wait for host buffers (pipeline_stalls_host), printed per card, says how long the chain held the source. Options: -i -s -N -B -C -S -X -t -k -m -K -v. docs/TOOLS.md rewritten to match, and docs/JFJOCH_BROKER.md no longer says a frame finding the stills hold full is dropped: it waits, and frames are lost only at the card. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01HVeDQrPqZ52Tp6rzzZGxf3 --- docs/JFJOCH_BROKER.md | 7 +- docs/TOOLS.md | 37 ++-- tools/jfjoch_fpga_stills_test.cpp | 295 +++++++++++------------------- 3 files changed, 120 insertions(+), 219 deletions(-) diff --git a/docs/JFJOCH_BROKER.md b/docs/JFJOCH_BROKER.md index d34c50e19..7e4ae2ecf 100644 --- a/docs/JFJOCH_BROKER.md +++ b/docs/JFJOCH_BROKER.md @@ -383,9 +383,10 @@ Frames arriving during the pre-pass, or faster than the analysis, wait in at mos of its slots hold a frame each (it can be seen through the image routes while it waits), the rest of that half holds frames as their compressed bytes, several to a slot; the other half is for the analysed frames, which go to the writer from a slot each, with one slot kept per analysis thread. The receiver's image memory is the image -buffer (`image_buffer_MiB`, `-B` of `jfjoch_fpga_stills_test`) and nothing beside it. A frame that finds the waiting -half full is dropped and counted as for a full image buffer, so analysis slower than the frame rate costs frames, -not memory. Where the writer lags behind, the analysis +buffer (`image_buffer_MiB`, `-B` of `jfjoch_fpga_stills_test`) and nothing beside it. No stage on the host discards a +frame: a frame that finds the waiting half full waits for room, and the wait goes back to the source - from FPGA +cards, `FPGAImagePuller` holds the cards' buffers and the cards wait for the host, so frames are lost only at the +card. Analysis slower than the frame rate thus costs frames at the card, not memory. Where the writer lags behind, the analysis waits for slots to come back. A pre-pass that fails leaves the stated geometry and mask in use. Where the start message cannot be sent after the pre-pass (no writer listening) or the analysis cannot be set up, the collection ends with that error, reported by `/status` and `/wait_till_done`, and the diff --git a/docs/TOOLS.md b/docs/TOOLS.md index c1baf283d..92b53c069 100644 --- a/docs/TOOLS.md +++ b/docs/TOOLS.md @@ -74,7 +74,7 @@ synthesis C model on the CPU, so no FPGA device is required. Measures rugnux live stills on the FPGA card(s), with a stored dataset standing in for the detector: ``` -jfjoch_fpga_stills_test [-i ] [-s ] [-N ] [-B ] [-C a,b,c,al,be,ga] [-X ] [-r ,...] [-p ] [-k ] [-m ] [-d] [-v] [-K[]] +jfjoch_fpga_stills_test [-i ] [-s ] [-N ] [-B ] [-C a,b,c,al,be,ga] [-S ] [-X ] [-t ] [-k ] [-m ] [-v] [-K[]] ``` - The dataset must be a stored JUNGFRAU dataset with its modules assembled (1030 x 514 each, any placement @@ -88,7 +88,7 @@ jfjoch_fpga_stills_test [-i ] [-s ] [-N ] [-B ] [-C - The frames are loaded into the card's internal frame generator and the run is made with the JUNGFRAU conversion off, so the card returns them verbatim; the host assembles them as signed 16-bit photon counts and rugnux live stills analyses them through `FPGAImagePuller`, as the broker does with rugnux live - on (`-d`: not blocking, as the broker runs; `-v`: each card's progress every 0.5 s; `-k `: analyse 1 of every + on (`-v`: each card's progress every 0.5 s; `-k `: analyse 1 of every F images on average, the rugnux live setting `stills_downsample`; `-m `: N frames summed into each image, by the card up to 256 and above that the largest divisor of N up to 256 on the card and the rest on the host, 32-bit images). Beam centre, distance, energy and the cell @@ -101,30 +101,17 @@ jfjoch_fpga_stills_test [-i ] [-s ] [-N ] [-B ] [-C apply here) and prints the mapping. These are the first ones of the file, cycled for the whole run of `-i` images (default: as many as the file has). **Images repeat**, so throughput, latency, spots per image and indexing rate are meaningful, the merge and its statistics are not. -- The run blocks at the source, no image is dropped: `FPGAImagePuller` waits for a free slot instead of - dropping an image (and gives no module up for being behind the others), the stills receiver waits for - room in the image buffer, so the card keeps its frames, its host writer waits for host buffers and the - stall reaches the internal generator through the card's AXI-stream back-pressure (the generator sits - before the network stack; a real detector's UDP packets would be lost at that point instead). The - firmware cannot pace the generator (it has no frame period): `-r` paces it from the host, the puller - taking image *i* from the cards no earlier than *i / rate* after the start, so the card waits for the - host either way. One collection is run per rate of `-r` (default `0`, as fast as it goes). `-r` is refused - with `-d`: holding a frame on the host makes the card wait, which is blocking again, and dropping the frames - that come early would keep a different subset on each card, as their generators run apart. +- One collection per invocation, as fast as it goes. Nothing on the host discards an image: `FPGAImagePuller` + waits for room in its queue to the receiver and the stills receiver for room in the image buffer, so the card + keeps its frames, its host writer waits for host buffers and the stall reaches the internal generator through + the card's AXI-stream back-pressure (the generator sits before the network stack; a real detector's UDP + packets would be lost at that point instead, the only place frames are lost). The card's own count of the + cycles it waited for host buffers is printed per card: how long the chain behind it held the source. - The cards' generators run free, each as fast as its modules' bandwidth allows, so cards with different - numbers of modules (a 9M on 4 cards: 5, 5, 4, 4) drift apart - unlike the modules of a detector, which a - common trigger keeps together - and with `-d` the images started by the cards ahead hold the puller's slots - until the frames of the card behind arrive. Where the modules do not divide evenly, every card is therefore - given as many modules as the largest, the rest dummy modules (zeros) the generator sends and the puller does - not read (`FPGAImagePuller::CardExperiment`; not part of the image, nor of its efficiency); `-U` leaves them - out. The start lines give each card's modules and dummies; the distinct images follow the padded count. With - `-U` (or cards that still drift, `-v` shows each card's frames) give `-p` at least the frames they drift apart. -- For each rate it reports the rate images were delivered (first to last image), the fraction of that time - the source was blocked by the chain behind it (the time the puller's module threads waited for a free - slot, mean over the modules), the sustained rate (images / wall time, start to the end of the analysis) - and the analysis rate after the pre-pass, and at the end a table of them: the highest rate with ~0% - blocked is the rate the live stills chain sustains. The card's own count of the cycles it waited for host - buffers is printed too; with `-r` it includes the pacing. + numbers of modules (a 9M on 4 cards: 5, 5, 4, 4) run at different speeds - unlike the modules of a detector, + which a common trigger keeps together; the run then goes at the pace of the slowest card. +- It reports the rate images were delivered (first to last image), the sustained rate (images / wall time, + start to the end of the analysis) and the analysis rate after the pre-pass. - At the end it prints images collected/sent/dropped, receiving time and frame rate, CPU use, indexing rate and spots per image, per-image times of the analysis stages, the pre-pass (time, beam centre and distance it decided), the latency from the last image to the end of the analysis and rugnux's steps. diff --git a/tools/jfjoch_fpga_stills_test.cpp b/tools/jfjoch_fpga_stills_test.cpp index d33901c3d..f9f441b29 100644 --- a/tools/jfjoch_fpga_stills_test.cpp +++ b/tools/jfjoch_fpga_stills_test.cpp @@ -11,7 +11,6 @@ #include #include #include -#include #include #include @@ -40,16 +39,9 @@ void print_usage(Logger &logger) { logger.Info(" -S Space group of the collection (a space group stored in the file is ignored)"); logger.Info(" -X Indexing (auto|fft|fftw|ffbidx), auto is default"); logger.Info(" -t Indexing thread pool size (default: 8, as offline rugnux on stills; the broker's default is 4)"); - logger.Info(" -r Rates the source is paced at, one collection each (default: 0 = as fast as it goes); the"); - logger.Info(" host takes frame i no earlier than i/rate, the card waits meanwhile: blocking runs only"); - logger.Info(" -p Images FPGAImagePuller keeps compressed for the receiver (default 128)"); - logger.Info(" -U No dummy modules: where the cards carry different numbers of modules, they run apart"); logger.Info(" -k Analyse 1 of every images on average (rugnux live stills_downsample, default 1)"); logger.Info(" -m Frames summed into an image (default 1): the card sums the largest divisor up to 256, the"); logger.Info(" host the rest (1000 = 250 on the card x 4 on the host)"); - logger.Info(" -d Not blocking, as the broker runs: images the host has no room for are dropped. The cards'"); - logger.Info(" generators run free, each at a speed that goes with its modules: where the modules do not"); - logger.Info(" divide evenly, each card is given dummy modules up to the largest count (-U: not)"); logger.Info(" -K{} Mock of the card instead of /dev/jfjoch* (optional: its generator memory, default 64 MiB ="); logger.Info(" 128 module frames)"); } @@ -94,9 +86,8 @@ int64_t GeneratorImages(AcquisitionDeviceGroup &aq_devices, const DiffractionExp // A stored dataset through the card and rugnux live stills; returns false where the run failed bool RunDataset(Logger &logger, AcquisitionDeviceGroup &aq_devices, const std::string &file, std::optional nimages, uint16_t nstreams, uint16_t nthreads, size_t send_buffer_size_MiB, - const IndexingSettings &indexing, const std::optional &cell, size_t puller_queue, - const std::vector &rates, bool dropping, bool pad, bool verbose, int64_t downsample, - const std::optional &space_group, int64_t summation) { + const IndexingSettings &indexing, const std::optional &cell, bool verbose, + int64_t downsample, const std::optional &space_group, int64_t summation) { RegisterHDF5Filter(); JFJochHDF5Reader reader; reader.ReadFile(file); @@ -133,18 +124,12 @@ bool RunDataset(Logger &logger, AcquisitionDeviceGroup &aq_devices, const std::s file_x.GetGemmiSpaceGroup()->hm); x.ImportIndexingSettings(indexing); - // The generator's speed goes with the modules of its card: with the modules not dividing evenly, every card is - // given as many as the largest, the rest dummies the puller does not read (FPGAImagePuller::CardExperiment) - const int64_t modules_per_card = (pad && (x.GetModulesNum() % nstreams != 0)) ? x.GetModulesNum(0) : 0; - DiffractionExperiment card_x = FPGAImagePuller::CardExperiment(x, modules_per_card); - - const int64_t generator_images = GeneratorImages(aq_devices, card_x, reader.GetNumberOfImages()); + const int64_t generator_images = GeneratorImages(aq_devices, x, reader.GetNumberOfImages()); if (generator_images < 1) { - logger.Error("The card memory cannot hold one image of {} modules", card_x.GetModulesNum(0)); + logger.Error("The card memory cannot hold one image of {} modules", x.GetModulesNum(0)); return false; } x.InternalPacketGeneratorImages(generator_images, FPGA_INTERNAL_GENERATOR_MAX_IMAGES); - card_x.InternalPacketGeneratorImages(generator_images, FPGA_INTERNAL_GENERATOR_MAX_IMAGES); PixelMask mask(x); if (dataset->pixel_mask->GetMask().size() == x.GetPixelsNum()) @@ -153,17 +138,9 @@ bool RunDataset(Logger &logger, AcquisitionDeviceGroup &aq_devices, const std::s logger.Info("Dataset {}: {} images of {} modules, {} distinct ones in the generator, {} in the run", file, reader.GetNumberOfImages(), x.GetModulesNum(), generator_images, x.GetImageNum()); for (int i = 0; i < x.GetDataStreamsNum(); i++) - logger.Info(" card {}: modules {}-{} and {} dummy, generator memory {} module frames, {} used", i, + logger.Info(" card {}: modules {}-{}, generator memory {} module frames, {} used", i, x.GetFirstModuleOfDataStream(i), x.GetFirstModuleOfDataStream(i) + x.GetModulesNum(i) - 1, - card_x.GetModulesNum(i) - x.GetModulesNum(i), aq_devices[i].GetInternalGeneratorModuleFrames(), - card_x.GetModulesNum(i) * generator_images); - if (dropping && !pad) { - for (int i = 1; i < x.GetDataStreamsNum(); i++) - if (x.GetModulesNum(i) != x.GetModulesNum(0)) { - logger.Warning("The cards carry different numbers of modules: their generators run apart (-U)"); - break; - } - } + aq_devices[i].GetInternalGeneratorModuleFrames(), x.GetModulesNum(i) * generator_images); for (int m = 0; m < x.GetModulesNum(); m++) logger.Debug(" module {}: pixel 0 at ({}, {}), fast step {}, slow step {}", m, x.GetPixel0OfModuleConv(m) % x.GetXPixelsNum(), x.GetPixel0OfModuleConv(m) / x.GetXPixelsNum(), @@ -175,146 +152,110 @@ bool RunDataset(Logger &logger, AcquisitionDeviceGroup &aq_devices, const std::s service.Indexing(x.GetIndexingSettings()); service.RugnuxLive(true, nullptr, 4, 60, false, false, downsample); - // Error, gap and beam-stop pixels of the reader become error pixels of the module frame. Card by card: each - // card's modules of the image, then its dummies (zeros) + // Error, gap and beam-stop pixels of the reader become error pixels of the module frame std::vector frame(x.GetModulesNum() * RAW_MODULE_SIZE); - std::vector card_frame(card_x.GetModulesNum() * RAW_MODULE_SIZE); + std::vector raw_frame(x.GetModulesNum() * RAW_MODULE_SIZE); for (int64_t i = 0; i < generator_images; i++) { const auto image = reader.LoadImage(i); SqueezeToRawGeometry(x, frame.data(), image->Image().data(), BEAM_STOP_PXL_VALUE, SATURATED_PXL_VALUE, INT16_MIN, INT16_MAX); - for (int d = 0; d < x.GetDataStreamsNum(); d++) - memcpy(card_frame.data() + card_x.GetFirstModuleOfDataStream(d) * RAW_MODULE_SIZE, - frame.data() + x.GetFirstModuleOfDataStream(d) * RAW_MODULE_SIZE, - x.GetModulesNum(d) * RAW_MODULE_SIZE * sizeof(int16_t)); - service.LoadInternalGeneratorImage(card_x, card_frame, i); - } - - struct Row { - double rate_hz, delivered_hz, blocked, sustained_hz, after_prepass_hz, indexing_rate; - uint64_t images, dropped; - }; - std::vector rows; - bool ok = true; - - for (const double rate: rates) { - // Blocking at source: the puller waits for a free slot and the receiver for room in the image buffer, - // the cards hold their frames and their generators stall - service.FPGAImagePullerSettings(puller_queue, !dropping, rate, false, modules_per_card); - logger.Info(""); - logger.Info("=== FPGAImagePuller (queue {}, {}), {} ===", puller_queue, dropping ? "dropping" : "blocking", - (rate > 0) ? fmt::format("source paced at {:.1f} Hz", rate) : std::string("source as fast as it goes")); - - rusage usage_start{}; - getrusage(RUSAGE_SELF, &usage_start); - const auto wall_start = std::chrono::steady_clock::now(); - - service.Start(x, mask, nullptr); - // -v: each card's progress, the frames of its fastest and slowest module written to the host - std::atomic running = true; - std::thread progress([&] { - while (running) { - std::this_thread::sleep_for(std::chrono::milliseconds(500)); - std::string line; - for (int i = 0; i < x.GetDataStreamsNum(); i++) - line += fmt::format(" card {}: {} .. {}{}", i, aq_devices[i].Counters().GetSlowestFrameNumber(), - aq_devices[i].Counters().GetFastestFrameNumber(), - aq_devices[i].Counters().IsAcquisitionFinished() ? " done" : ""); - // Where a run stands, so that one that stops shows which part waits - if (const auto st = service.GetStatus()) - line += fmt::format(" receiver: collected {} sent {} dropped {}", st->images_collected, - st->images_sent, st->images_dropped); - const auto live = service.GetRugnuxStatus(); - if (live.stills) - line += fmt::format(" stills: held {} analysed {} pre-pass {}", live.stills->images_held, - live.stills->images_analysed, static_cast(live.stills->prepass)); - if (verbose) - logger.Info("{:.1f} s{}", std::chrono::duration(std::chrono::steady_clock::now() - - wall_start).count(), line); - } - }); - const auto output = service.Stop(); - running = false; - progress.join(); - const auto live = service.GetRugnuxStatus(); - - const double wall_time = std::chrono::duration(std::chrono::steady_clock::now() - wall_start).count(); - rusage usage_end{}; - getrusage(RUSAGE_SELF, &usage_end); - auto seconds = [](const timeval &t) { return static_cast(t.tv_sec) + static_cast(t.tv_usec) / 1e6; }; - const double cpu_time = seconds(usage_end.ru_utime) - seconds(usage_start.ru_utime) - + seconds(usage_end.ru_stime) - seconds(usage_start.ru_stime); - - int64_t spots = 0, spot_images = 0; - for (const auto &e: output.scan_result.images) - if (e.spot_count) { - spots += e.spot_count.value(); - spot_images++; - } - - // From the first image to the last one into the receiver; the source was blocked for the time the module - // threads waited for a free slot, as a fraction of that span (mean over the modules) - const double delivery_s = live.last_image_s.value_or(0); - const double delivered_hz = (delivery_s > 0) ? static_cast(output.status.images_collected - 1) / delivery_s : 0; - const double blocked = (delivery_s > 0) ? service.GetFPGAImagePullerQueueWaitTime_s() / delivery_s : 0; - - logger.Info("Images expected {} collected {} sent {} dropped {} efficiency {:.4f}", - x.GetImageNum(), output.status.images_collected, output.status.images_sent, - output.status.images_dropped, output.efficiency); - logger.Info("Delivered {:.1f} Hz (first to last image {:.2f} s), source blocked {:.1f}% of it", - delivered_hz, delivery_s, 100.0 * blocked); - logger.Info("Sustained {:.1f} Hz (images / wall time {:.2f} s, start to analysis done) CPU {:.1f} s = {:.1f} cores" - " max resident memory {:.1f} GiB", - static_cast(output.status.images_collected) / wall_time, wall_time, cpu_time, - cpu_time / wall_time, static_cast(usage_end.ru_maxrss) / (1024.0 * 1024.0)); - // The card's own count of the cycles (200 MHz) it waited for a host buffer, i.e. was held by the host - for (int i = 0; i < x.GetDataStreamsNum(); i++) { - const auto status = aq_devices[i].GetDataCollectionStatus(); - logger.Info("Card {}: waited for host buffers {:.2f} s ({:.1f}% of the delivery), stalls before HBM {} cycles", - i, status.pipeline_stalls_host / 200e6, - (delivery_s > 0) ? 100.0 * status.pipeline_stalls_host / 200e6 / delivery_s : 0.0, - status.pipeline_stalls_hbm); - } - logger.Info("Indexing rate {:.3f} spots per image {:.1f}", output.status.indexing_rate.value_or(0), - static_cast(spots) / std::max(1, spot_images)); - logger.Info("Per-image time (mean; microseconds): preprocess {:.0f} spot finding {:.0f} indexing {:.0f} " - "refinement {:.0f} integration {:.0f} total {:.0f}", - output.processing_time.preprocessing * 1e6, output.processing_time.spot_finding * 1e6, - output.processing_time.indexing * 1e6, output.processing_time.refinement * 1e6, - output.processing_time.integration * 1e6, output.processing_time.processing * 1e6); - double after_prepass_hz = 0; - if (live.stills) { - const auto &st = *live.stills; - after_prepass_hz = st.analysis_rate_hz.value_or(0); - logger.Info("Pre-pass {:.2f} s: beam {:.2f} {:.2f} px (file {:.2f} {:.2f}), distance {:.2f} mm (file {:.2f})", - st.prepass_s.value_or(0), st.beam_x_pxl.value_or(NAN), st.beam_y_pxl.value_or(NAN), - st.file_beam_x_pxl, st.file_beam_y_pxl, st.distance_mm.value_or(NAN), st.file_distance_mm); - logger.Info("Analysed {} ({:.3f} of the images) indexed {} analysis rate after the pre-pass {:.1f} Hz", - st.images_analysed, static_cast(st.images_analysed) / x.GetImageNum(), - st.images_indexed, after_prepass_hz); - } - logger.Info("Rugnux: {} {} last image at {:.2f} s, done {:.2f} s after it", live.verdict, live.message, - live.last_image_s.value_or(NAN), live.last_image_to_written_s.value_or(NAN)); - for (const auto &step: live.steps) - logger.Info(" step {:.2f} s + {:.2f} s {}", step.started_s, step.duration_s.value_or(NAN), step.title); - - rows.push_back(Row{.rate_hz = rate, .delivered_hz = delivered_hz, .blocked = blocked, - .sustained_hz = static_cast(output.status.images_collected) / wall_time, - .after_prepass_hz = after_prepass_hz, - .indexing_rate = output.status.indexing_rate.value_or(0), - .images = output.status.images_collected, .dropped = output.status.images_dropped}); - ok = ok && (output.efficiency > 0) && (live.state == RugnuxLiveState::Done); + memcpy(raw_frame.data(), frame.data(), frame.size() * sizeof(int16_t)); + service.LoadInternalGeneratorImage(x, raw_frame, i); } logger.Info(""); - logger.Info("=== Rates ({} images, {} distinct: images repeat, the merge and its statistics are not a measure of the data) ===", - x.GetImageNum(), generator_images); - logger.Info(" source Hz delivered Hz blocked sustained Hz after pre-pass Hz indexing images dropped"); - for (const auto &r: rows) - logger.Info(" {:>9} {:>12.1f} {:>6.1f}% {:>12.1f} {:>17.1f} {:>8.3f} {:>6} {:>7}", - (r.rate_hz > 0) ? fmt::format("{:.1f}", r.rate_hz) : std::string("max"), r.delivered_hz, - 100.0 * r.blocked, r.sustained_hz, r.after_prepass_hz, r.indexing_rate, r.images, r.dropped); - return ok; + logger.Info("=== FPGAImagePuller, {} images ===", x.GetImageNum()); + + rusage usage_start{}; + getrusage(RUSAGE_SELF, &usage_start); + const auto wall_start = std::chrono::steady_clock::now(); + + service.Start(x, mask, nullptr); + // -v: each card's progress, the frames of its fastest and slowest module written to the host + std::atomic running = true; + std::thread progress([&] { + while (running) { + std::this_thread::sleep_for(std::chrono::milliseconds(500)); + std::string line; + for (int i = 0; i < x.GetDataStreamsNum(); i++) + line += fmt::format(" card {}: {} .. {}{}", i, aq_devices[i].Counters().GetSlowestFrameNumber(), + aq_devices[i].Counters().GetFastestFrameNumber(), + aq_devices[i].Counters().IsAcquisitionFinished() ? " done" : ""); + // Where a run stands, so that one that stops shows which part waits + if (const auto st = service.GetStatus()) + line += fmt::format(" receiver: collected {} sent {} dropped {}", st->images_collected, + st->images_sent, st->images_dropped); + const auto live = service.GetRugnuxStatus(); + if (live.stills) + line += fmt::format(" stills: held {} analysed {} pre-pass {}", live.stills->images_held, + live.stills->images_analysed, static_cast(live.stills->prepass)); + if (verbose) + logger.Info("{:.1f} s{}", std::chrono::duration(std::chrono::steady_clock::now() + - wall_start).count(), line); + } + }); + const auto output = service.Stop(); + running = false; + progress.join(); + const auto live = service.GetRugnuxStatus(); + + const double wall_time = std::chrono::duration(std::chrono::steady_clock::now() - wall_start).count(); + rusage usage_end{}; + getrusage(RUSAGE_SELF, &usage_end); + auto seconds = [](const timeval &t) { return static_cast(t.tv_sec) + static_cast(t.tv_usec) / 1e6; }; + const double cpu_time = seconds(usage_end.ru_utime) - seconds(usage_start.ru_utime) + + seconds(usage_end.ru_stime) - seconds(usage_start.ru_stime); + + int64_t spots = 0, spot_images = 0; + for (const auto &e: output.scan_result.images) + if (e.spot_count) { + spots += e.spot_count.value(); + spot_images++; + } + + // From the first image to the last one into the receiver + const double delivery_s = live.last_image_s.value_or(0); + const double delivered_hz = (delivery_s > 0) ? static_cast(output.status.images_collected - 1) / delivery_s : 0; + + logger.Info("Images expected {} collected {} sent {} dropped {} efficiency {:.4f}", + x.GetImageNum(), output.status.images_collected, output.status.images_sent, + output.status.images_dropped, output.efficiency); + logger.Info("Delivered {:.1f} Hz (first to last image {:.2f} s)", delivered_hz, delivery_s); + logger.Info("Sustained {:.1f} Hz (images / wall time {:.2f} s, start to analysis done) CPU {:.1f} s = {:.1f} cores" + " max resident memory {:.1f} GiB", + static_cast(output.status.images_collected) / wall_time, wall_time, cpu_time, + cpu_time / wall_time, static_cast(usage_end.ru_maxrss) / (1024.0 * 1024.0)); + // The card's own count of the cycles (200 MHz) it waited for a host buffer, i.e. was held by the host: the + // source blocked + for (int i = 0; i < x.GetDataStreamsNum(); i++) { + const auto status = aq_devices[i].GetDataCollectionStatus(); + logger.Info("Card {}: waited for host buffers {:.2f} s ({:.1f}% of the delivery), stalls before HBM {} cycles", + i, status.pipeline_stalls_host / 200e6, + (delivery_s > 0) ? 100.0 * status.pipeline_stalls_host / 200e6 / delivery_s : 0.0, + status.pipeline_stalls_hbm); + } + logger.Info("Indexing rate {:.3f} spots per image {:.1f}", output.status.indexing_rate.value_or(0), + static_cast(spots) / std::max(1, spot_images)); + logger.Info("Per-image time (mean; microseconds): preprocess {:.0f} spot finding {:.0f} indexing {:.0f} " + "refinement {:.0f} integration {:.0f} total {:.0f}", + output.processing_time.preprocessing * 1e6, output.processing_time.spot_finding * 1e6, + output.processing_time.indexing * 1e6, output.processing_time.refinement * 1e6, + output.processing_time.integration * 1e6, output.processing_time.processing * 1e6); + if (live.stills) { + const auto &st = *live.stills; + logger.Info("Pre-pass {:.2f} s: beam {:.2f} {:.2f} px (file {:.2f} {:.2f}), distance {:.2f} mm (file {:.2f})", + st.prepass_s.value_or(0), st.beam_x_pxl.value_or(NAN), st.beam_y_pxl.value_or(NAN), + st.file_beam_x_pxl, st.file_beam_y_pxl, st.distance_mm.value_or(NAN), st.file_distance_mm); + logger.Info("Analysed {} ({:.3f} of the images) indexed {} analysis rate after the pre-pass {:.1f} Hz", + st.images_analysed, static_cast(st.images_analysed) / x.GetImageNum(), + st.images_indexed, st.analysis_rate_hz.value_or(0)); + } + logger.Info("Rugnux: {} {} last image at {:.2f} s, done {:.2f} s after it", live.verdict, live.message, + live.last_image_s.value_or(NAN), live.last_image_to_written_s.value_or(NAN)); + for (const auto &step: live.steps) + logger.Info(" step {:.2f} s + {:.2f} s {}", step.started_s, step.duration_s.value_or(NAN), step.title); + + return (output.efficiency > 0) && (live.state == RugnuxLiveState::Done); } int main(int argc, char **argv) { @@ -330,18 +271,14 @@ int main(int argc, char **argv) { std::optional cell; IndexingAlgorithmEnum indexing = IndexingAlgorithmEnum::Auto; uint16_t indexing_threads = 8; // as offline rugnux's stills (Rugnux::StillsIndexerThreads) - size_t puller_queue = FPGAImagePuller::DefaultQueue; std::optional mock_card_MiB; bool verbose = false; - std::vector rates = {0}; - bool dropping = false; - bool pad = true; int64_t downsample = 1; int64_t summation = 1; std::optional space_group; int opt; - while ((opt = getopt(argc, argv, "vi:s:N:B:C:S:X:t:r:p:dUk:m:K::")) != -1) { + while ((opt = getopt(argc, argv, "vi:s:N:B:C:S:X:t:k:m:K::")) != -1) { switch (opt) { case 'v': verbose = true; @@ -380,23 +317,6 @@ int main(int argc, char **argv) { case 't': indexing_threads = atol(optarg); break; - case 'r': { - rates.clear(); - std::stringstream list(optarg); - std::string rate; - while (std::getline(list, rate, ',')) - rates.push_back(atof(rate.c_str())); - break; - } - case 'p': - puller_queue = atol(optarg); - break; - case 'd': - dropping = true; - break; - case 'U': - pad = false; - break; case 'k': downsample = atol(optarg); break; @@ -425,13 +345,6 @@ int main(int argc, char **argv) { print_usage(logger); exit(EXIT_FAILURE); } - // The generator has no frame period: -r holds frames on the host, which makes the card wait - blocking again. - // Dropping the frames that come early instead would keep a different subset on each card, as they run apart. - if (dropping && std::any_of(rates.begin(), rates.end(), [](double r) { return r > 0; })) { - logger.Error("-r paces the source through the card waiting for the host, so it cannot be used with -d"); - exit(EXIT_FAILURE); - } - // -v gives the progress lines only: the debug log has a line for every module frame logger.Verbose(false); @@ -454,7 +367,7 @@ int main(int argc, char **argv) { bool ret = false; try { ret = RunDataset(logger, aq_devices, argv[optind], nimages, nstreams, nthreads, send_buffer_size_MiB, - i_settings, cell, puller_queue, rates, dropping, pad, verbose, downsample, space_group, + i_settings, cell, verbose, downsample, space_group, summation); } catch (std::exception &e) { logger.Error(e.what()); From d92186332c721f23bd85ff84582f35b33681814c Mon Sep 17 00:00:00 2001 From: Filip Leonarski Date: Wed, 18 Nov 2026 19:53:43 +0100 Subject: [PATCH 37/41] FPGAImagePuller tests: one slow-consumer case, nothing lost; silent end delivers all Removed SlowConsumer_Puller, Paced and DroppingNoLockInversion (paths that no longer exist). SlowConsumer: 300 images, more than the queue and the mock's buffers hold, none lost, in order, and the mock card waited for host buffers (pipeline_stalls_host > 0). CancelWithoutConsumer keeps its hang guard. SlowConsumer_Receiver: no loss behind a slow writer. New SilentEndDeliversAll: a silent cancel after the card is through still brings every image to a slow writer. MissingModule ends the cards with StopCards(). FPGAImagePullerSettings(bool) in the callers. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01HVeDQrPqZ52Tp6rzzZGxf3 --- tests/FPGAImagePullerSummationTest.cpp | 2 +- tests/FPGAImagePullerTest.cpp | 187 ++++++++----------------- 2 files changed, 59 insertions(+), 130 deletions(-) diff --git a/tests/FPGAImagePullerSummationTest.cpp b/tests/FPGAImagePullerSummationTest.cpp index f8c8ef986..23adc8398 100644 --- a/tests/FPGAImagePullerSummationTest.cpp +++ b/tests/FPGAImagePullerSummationTest.cpp @@ -129,7 +129,7 @@ namespace { SpotFindingSettings spots = DiffractionExperiment::DefaultDataProcessingSettings(); spots.indexing = false; service.NumThreads(4).SetSpotFindingSettings(spots); - service.FPGAImagePullerSettings(FPGAImagePuller::DefaultQueue, false, 0, puller); + service.FPGAImagePullerSettings(puller); PixelMask mask(x); const JFCalibration calib = GeneratePedestalCalibration(x); service.Start(x, mask, &calib); diff --git a/tests/FPGAImagePullerTest.cpp b/tests/FPGAImagePullerTest.cpp index fee2d6f08..2ca220e77 100644 --- a/tests/FPGAImagePullerTest.cpp +++ b/tests/FPGAImagePullerTest.cpp @@ -166,7 +166,7 @@ namespace { JFJochReceiverService service(devices, logger, pusher, 256); service.NumThreads(4); service.SetSpotFindingSettings(Spots()); - service.FPGAImagePullerSettings(FPGAImagePuller::DefaultQueue, false, 0, puller); + service.FPGAImagePullerSettings(puller); service.RugnuxLive(rugnux, nullptr, 2, 30); PixelMask mask(x); @@ -420,7 +420,7 @@ TEST_CASE("FPGAImagePuller_SameAsFPGA_EIGER_32bit", "[FPGAImagePuller]") { CollectingPusher pusher; JFJochReceiverService service(devices, logger, pusher, 256); service.NumThreads(4).SetSpotFindingSettings(Spots()); - service.FPGAImagePullerSettings(FPGAImagePuller::DefaultQueue, false, 0, puller); + service.FPGAImagePullerSettings(puller); PixelMask mask(x); service.Start(x, mask, nullptr); const auto out = service.Stop(); @@ -430,9 +430,11 @@ TEST_CASE("FPGAImagePuller_SameAsFPGA_EIGER_32bit", "[FPGAImagePuller]") { } } -// Nobody takes the images: the slots run out and later images are dropped whole, without any waiting. -TEST_CASE("FPGAImagePuller_SlowConsumer_Puller", "[FPGAImagePuller]") { - auto x = Base(DetJF(1), 20, 1); +// A slow consumer: nothing is lost on the host, the images come in order and the card waits for its buffers +TEST_CASE("FPGAImagePuller_SlowConsumer", "[FPGAImagePuller]") { + // More images than the queue and the card's 64 buffers hold together + constexpr int64_t images = 300; + auto x = Base(DetJF(1), images, 1); x.Conversion(); x.Compression(CompressionAlgorithm::BSHUF_LZ4); @@ -440,51 +442,13 @@ TEST_CASE("FPGAImagePuller_SlowConsumer_Puller", "[FPGAImagePuller]") { Logger logger("FPGAImagePuller_SlowConsumer"); PixelMask mask(x); const JFCalibration calib = Calibration(x); - FPGAImagePuller puller(x, mask, &calib, devices, logger, 2, 4); - - // Not read until the card is through, however long the simulation takes - while (!devices[0].Counters().IsAcquisitionFinished()) - std::this_thread::sleep_for(10ms); - - std::vector numbers; - bool end = false; - const auto t0 = std::chrono::steady_clock::now(); - while (!end && std::chrono::steady_clock::now() - t0 < 60s) { - const auto m = puller.PollImage(10ms); - if (!m) - continue; - if (m->cbor->data_message) - numbers.push_back(m->cbor->data_message->number); - end = m->cbor->end_message.has_value(); - } - CHECK(end); - puller.Stop(); - std::cout << "slow consumer, puller alone: " << numbers.size() << " images, " - << puller.GetDroppedImages() << " dropped" << std::endl; - CHECK(numbers.size() + puller.GetDroppedImages() == 20); - CHECK(puller.GetDroppedImages() > 0); - for (size_t i = 1; i < numbers.size(); i++) - CHECK(numbers[i] > numbers[i - 1]); -} - -// Blocking: the same slow consumer, nothing is dropped - the card waits for its buffers instead -TEST_CASE("FPGAImagePuller_SlowConsumer_Blocking", "[FPGAImagePuller]") { - auto x = Base(DetJF(1), 20, 1); - x.Conversion(); - x.Compression(CompressionAlgorithm::BSHUF_LZ4); - - auto devices = Devices(x); - Logger logger("FPGAImagePuller_SlowConsumer_Blocking"); - PixelMask mask(x); - const JFCalibration calib = Calibration(x); - FPGAImagePuller puller(x, mask, &calib, devices, logger, 2, 4, true); - REQUIRE(puller.IsBlocking()); + FPGAImagePuller puller(x, mask, &calib, devices, logger, 2); std::this_thread::sleep_for(2s); std::vector numbers; bool end = false; const auto t0 = std::chrono::steady_clock::now(); - while (!end && std::chrono::steady_clock::now() - t0 < 60s) { + while (!end && std::chrono::steady_clock::now() - t0 < 120s) { const auto m = puller.PollImage(10ms); if (!m) continue; @@ -494,24 +458,23 @@ TEST_CASE("FPGAImagePuller_SlowConsumer_Blocking", "[FPGAImagePuller]") { } CHECK(end); puller.Stop(); - CHECK(puller.GetDroppedImages() == 0); - CHECK(puller.GetQueueWaitTime_s() > 0.5); - REQUIRE(numbers.size() == 20); + CHECK(devices[0].GetDataCollectionStatus().pipeline_stalls_host > 0); + REQUIRE(numbers.size() == images); for (size_t i = 0; i < numbers.size(); i++) CHECK(numbers[i] == static_cast(i)); } -// Blocking, and nobody takes the images: a cancel must still end the puller (the images waiting for a slot are -// dropped). Run on a thread of its own, so that a hang fails the test instead of stopping the run. -TEST_CASE("FPGAImagePuller_Blocking_CancelWithoutConsumer", "[FPGAImagePuller]") { - auto x = Base(DetJF(1), 20, 1); +// Nobody takes the images: a cancel must still end the puller. Run on a thread of its own, so that a hang fails the +// test instead of stopping the run. +TEST_CASE("FPGAImagePuller_CancelWithoutConsumer", "[FPGAImagePuller]") { + auto x = Base(DetJF(1), 300, 1); x.Conversion(); x.Compression(CompressionAlgorithm::BSHUF_LZ4); auto devices = std::make_shared(Devices(x)); - auto logger = std::make_shared("FPGAImagePuller_Blocking_Cancel"); + auto logger = std::make_shared("FPGAImagePuller_CancelWithoutConsumer"); auto mask = std::make_shared(x); - auto puller = std::make_shared(x, *mask, nullptr, *devices, *logger, 2, 2, true); + auto puller = std::make_shared(x, *mask, nullptr, *devices, *logger, 2); std::this_thread::sleep_for(1s); auto stopped = std::make_shared>(); @@ -524,74 +487,9 @@ TEST_CASE("FPGAImagePuller_Blocking_CancelWithoutConsumer", "[FPGAImagePuller]") stopped->set_value(); }).detach(); REQUIRE(done.wait_for(30s) == std::future_status::ready); - CHECK(puller->GetDroppedImages() > 0); } -// Not blocking, with drops: a module thread drops an image (GetSlot, images_mutex) while a compress thread lets an -// image out (Emit, order_mutex) and the consumer frees images at once, so a slot can go back from inside Emit. The -// two locks must never be held the other way round. Run on a thread of its own, so that a hang fails the test. -TEST_CASE("FPGAImagePuller_DroppingNoLockInversion", "[FPGAImagePuller]") { - auto x = Base(DetJF(4), 3000, 1); - x.Conversion(); - x.Compression(CompressionAlgorithm::NO_COMPRESSION); - - auto devices = std::make_shared(Devices(x)); - auto logger = std::make_shared("FPGAImagePuller_DroppingNoLockInversion"); - auto mask = std::make_shared(x); - auto finished = std::make_shared>(); - auto done = finished->get_future(); - std::thread([x, devices, logger, mask, finished] { - FPGAImagePuller puller(x, *mask, nullptr, *devices, *logger, 8, 2); - size_t images = 0; - bool end = false; - while (!end) { - // Now and then the consumer pauses, so that the slots run out and images are dropped - if (images % 7 == 0) - std::this_thread::sleep_for(1ms); - const auto m = puller.PollImage(10ms); - if (m && m->cbor->data_message) - images++; - end = m && m->cbor->end_message.has_value(); - } - puller.Stop(); - std::cout << "dropping, no lock inversion: " << images << " images, " << puller.GetDroppedImages() - << " dropped" << std::endl; - finished->set_value(images + puller.GetDroppedImages()); - }).detach(); - REQUIRE(done.wait_for(120s) == std::future_status::ready); - CHECK(done.get() <= 3000); -} - -// Paced: the images are taken from the card at most at the rate given -TEST_CASE("FPGAImagePuller_Paced", "[FPGAImagePuller]") { - auto x = Base(DetJF(1), 10, 1); - x.Conversion(); - x.Compression(CompressionAlgorithm::BSHUF_LZ4); - - auto devices = Devices(x); - Logger logger("FPGAImagePuller_Paced"); - PixelMask mask(x); - const JFCalibration calib = Calibration(x); - const auto t0 = std::chrono::steady_clock::now(); - FPGAImagePuller puller(x, mask, &calib, devices, logger, 2, 16, true, 10.0); - - size_t images = 0; - bool end = false; - while (!end && std::chrono::steady_clock::now() - t0 < 60s) { - const auto m = puller.PollImage(10ms); - if (!m) - continue; - if (m->cbor->data_message) - images++; - end = m->cbor->end_message.has_value(); - } - puller.Stop(); - CHECK(images == 10); - // Image 9 is taken 0.9 s after the start at the earliest - CHECK(std::chrono::steady_clock::now() - t0 > 900ms); -} - -// The same behind Lite: a writer that takes its time keeps Lite's only thread, and the drops reach the statistics. +// The same behind Lite: a writer that takes its time holds Lite's only thread, and nothing is lost on the way. TEST_CASE("FPGAImagePuller_SlowConsumer_Receiver", "[FPGAImagePuller]") { auto x = Base(DetJF(1), 24, 1); x.Conversion(); @@ -600,10 +498,10 @@ TEST_CASE("FPGAImagePuller_SlowConsumer_Receiver", "[FPGAImagePuller]") { auto devices = Devices(x); Logger logger("FPGAImagePuller_SlowReceiver"); CollectingPusher pusher; - pusher.delay = 3s; + pusher.delay = 200ms; JFJochReceiverService service(devices, logger, pusher, 256); service.NumThreads(1).SetSpotFindingSettings(Spots()); - service.FPGAImagePullerSettings(2, false, 0, true); + service.FPGAImagePullerSettings(true); PixelMask mask(x); const JFCalibration calib = Calibration(x); @@ -612,9 +510,40 @@ TEST_CASE("FPGAImagePuller_SlowConsumer_Receiver", "[FPGAImagePuller]") { std::cout << "slow consumer, Lite: collected " << out.status.images_collected << " dropped " << out.status.images_dropped << " efficiency " << out.efficiency << std::endl; - CHECK(out.status.images_dropped > 0); - CHECK(out.status.images_collected + out.status.images_dropped == 24); - CHECK(out.efficiency == Catch::Approx(static_cast(out.status.images_collected) / 24.0f)); + CHECK(out.status.images_dropped == 0); + CHECK(out.status.images_collected == 24); + CHECK(out.efficiency == 1.0f); + CHECK(pusher.images.size() == 24); + CHECK(pusher.sequence.back() == "end"); +} + +// The broker ends every run with a silent cancel once the detector is done: every image still reaches the writer, +// however slow it is. +TEST_CASE("FPGAImagePuller_SilentEndDeliversAll", "[FPGAImagePuller]") { + auto x = Base(DetJF(1), 24, 1); + x.Conversion(); + x.Compression(CompressionAlgorithm::BSHUF_LZ4); + + auto devices = Devices(x); + Logger logger("FPGAImagePuller_SilentEnd"); + CollectingPusher pusher; + pusher.delay = 200ms; + JFJochReceiverService service(devices, logger, pusher, 256); + service.NumThreads(1).SetSpotFindingSettings(Spots()); + service.FPGAImagePullerSettings(true); + + PixelMask mask(x); + const JFCalibration calib = Calibration(x); + service.Start(x, mask, &calib); + // The card is through, the writer far behind + while (!devices[0].Counters().IsAcquisitionFinished()) + std::this_thread::sleep_for(10ms); + service.Cancel(true); + const auto out = service.Stop(); + + CHECK(!out.status.cancelled); + CHECK(out.status.images_collected == 24); + CHECK(pusher.images.size() == 24); CHECK(pusher.sequence.back() == "end"); } @@ -659,7 +588,7 @@ TEST_CASE("FPGAImagePuller_MissingModule", "[FPGAImagePuller]") { << " module 0 at " << devices[0].Counters().GetCurrFrameNumber(0) << " module 1 at " << devices[0].Counters().GetCurrFrameNumber(1) << " images so far " << numbers.size() << std::endl; - puller.Cancel(); + puller.StopCards(); } continue; } @@ -716,7 +645,7 @@ TEST_CASE("FPGAImagePuller_Cancel", "[FPGAImagePuller]") { CollectingPusher pusher; JFJochReceiverService service(devices, logger, pusher, 256); service.NumThreads(2).SetSpotFindingSettings(Spots()); - service.FPGAImagePullerSettings(FPGAImagePuller::DefaultQueue, false, 0, true); + service.FPGAImagePullerSettings(true); PixelMask mask(x); const JFCalibration calib = Calibration(x); service.Start(x, mask, &calib); @@ -751,7 +680,7 @@ TEST_CASE("FPGAImagePuller_HostSummation", "[FPGAImagePuller]") { CollectingPusher pusher; JFJochReceiverService service(devices, logger, pusher, 256); service.NumThreads(4).SetSpotFindingSettings(Spots()); - service.FPGAImagePullerSettings(FPGAImagePuller::DefaultQueue, false, 0, true); + service.FPGAImagePullerSettings(true); PixelMask mask(x); const JFCalibration calib = Calibration(x); service.Start(x, mask, &calib); @@ -922,7 +851,7 @@ TEST_CASE("FPGAImagePuller_Writer", "[FPGAImagePuller]") { HDF5FilePusher pusher; JFJochReceiverService service(devices, logger, pusher, 256); service.NumThreads(2).SetSpotFindingSettings(Spots()); - service.FPGAImagePullerSettings(FPGAImagePuller::DefaultQueue, false, 0, true); + service.FPGAImagePullerSettings(true); PixelMask mask(x); const JFCalibration calib = Calibration(x); service.Start(x, mask, &calib); From b7518fe17ebe24669f8a23bbad4ab236b4e986b5 Mon Sep 17 00:00:00 2001 From: Filip Leonarski Date: Wed, 18 Nov 2026 20:06:37 +0100 Subject: [PATCH 38/41] Live stills hold: packed only, frames seen by lookup, the stream waits when it is full As the Fable review proposed and the owner decided: - HoldArena is the only hold: the quarter of single-frame slots of 4c9cc4838 (visible_held, visible_max) is gone. A waiting frame is seen by lookup: the receiver keeps image number -> (weak_ptr, the message as it came), inserted in OnImage, erased when the frame is sent. JFJochReceiver:: GetWaitingImage (default: none) serialises it, its image in the hold, into the output while it holds the frame; GetLastWaitingImage gives the latest. JFJochReceiverService::GetImageFromBuffer (and the JPEG and TIFF routes) try the image buffer first, then the receiver; MaxImage takes the later of the two. ImageBuffer is unchanged. - The pre-pass holds up to PREPASS_MAX_IMAGES; it starts when the hold has no room for another frame (HoldArena::Full), on what is held. - One behaviour, no IsBlocking(): a frame that finds the hold full waits while the collection is not cancelled, and the pre-pass and the analysis drain it. No frame is lost at the hold; a source faster than the analysis loses frames at the card. An analysed frame that finds no slot to be written from within 2 s is still not written and counted (writer_queue_full), as before. Tests: ImagesVisibleDuringPrePass sees every waiting frame by lookup (and no slot in sending); BufferFullDuringPrePass, 200 frames into a 12-slot buffer, writes them all with no loss; CancelDuringRun gives frames until the pre-pass starts (the hold full) instead of relying on a six-frame pre-pass. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01HVeDQrPqZ52Tp6rzzZGxf3 --- docs/JFJOCH_BROKER.md | 16 ++-- receiver/HoldArena.h | 11 +++ receiver/JFJochReceiver.h | 6 ++ receiver/JFJochReceiverRugnuxStills.cpp | 108 +++++++++++------------- receiver/JFJochReceiverRugnuxStills.h | 20 +++-- receiver/JFJochReceiverService.cpp | 15 +++- receiver/StillsGPUAnalysis.h | 3 +- tests/JFJochReceiverRugnuxTest.cpp | 36 +++++--- 8 files changed, 127 insertions(+), 88 deletions(-) diff --git a/docs/JFJOCH_BROKER.md b/docs/JFJOCH_BROKER.md index 43e3b31f4..a9b92b444 100644 --- a/docs/JFJOCH_BROKER.md +++ b/docs/JFJOCH_BROKER.md @@ -373,14 +373,14 @@ of its frames indexed, as with a small image buffer, a low hit rate or a chip wh cell given), the distance in the header is used for the whole run: this is a warning in the log and a note of the live status, and a wrong header distance then costs resolution and indexed frames. -Frames arriving during the pre-pass, or faster than the analysis, wait in at most half of the image buffer: a quarter -of its slots hold a frame each (it can be seen through the image routes while it waits), the rest of that half -holds frames as their compressed bytes, several to a slot; the other half is for the analysed frames, which go to -the writer from a slot each, with one slot kept per analysis thread. The receiver's image memory is the image -buffer (`image_buffer_MiB`, `-B` of `jfjoch_fpga_stills_test`) and nothing beside it. A frame that finds the waiting -half full is dropped and counted as for a full image buffer, so analysis slower than the frame rate costs frames, -not memory. Where the writer lags behind, the analysis -waits for slots to come back. A pre-pass that fails leaves the stated geometry and +Frames arriving during the pre-pass, or faster than the analysis, wait in at most half of the image buffer, as their +compressed bytes, several to a slot; the image routes serve them from there, by number, while they wait. The other +half is for the analysed frames, which go to the writer from a slot each, with one slot kept per analysis thread. +The pre-pass takes at most 2000 frames, fewer where the waiting half fills first: then it starts on what it has. The +receiver's image memory is the image buffer (`image_buffer_MiB`, `-B` of `jfjoch_fpga_stills_test`) and nothing +beside it. A frame that finds the waiting half full waits until the analysis has made room; frames are not dropped +there, so analysis slower than the frame rate holds the stream back, and frames are lost at the card. An analysed +frame that finds no slot to be written from within 2 s is not written and is counted as for a full image buffer. A pre-pass that fails leaves the stated geometry and mask in use. Where the start message cannot be sent after the pre-pass (no writer listening) or the analysis cannot be set up, the collection ends with that error, reported by `/status` and `/wait_till_done`, and the next `/start` runs as usual. diff --git a/receiver/HoldArena.h b/receiver/HoldArena.h index ebfeaf5b7..dab478bf0 100644 --- a/receiver/HoldArena.h +++ b/receiver/HoldArena.h @@ -83,6 +83,17 @@ public: return ret; } + // No room for a frame of this size without a frame going first + bool Full(size_t size) { + std::unique_lock ul(m); + if (current != SIZE_MAX && chunks[current].used + size <= slot_size) + return false; + for (const auto &c: chunks) + if (c.slot && c.frames == 0) + return false; + return static_cast(chunks.size()) >= max_slots; + } + int64_t GetSlotsUsed() { std::unique_lock ul(m); return static_cast(chunks.size()); diff --git a/receiver/JFJochReceiver.h b/receiver/JFJochReceiver.h index 693d52a83..a2ff2f651 100644 --- a/receiver/JFJochReceiver.h +++ b/receiver/JFJochReceiver.h @@ -131,6 +131,12 @@ public: virtual void SetSpotFindingSettings(const SpotFindingSettings &spot_finding_settings); virtual JFJochReceiverOutput GetFinalStatistics() const; + + // A frame the receiver holds and has not sent to the image buffer yet, serialised as the buffer serves an image; + // false where there is none of that number + virtual bool GetWaitingImage(std::vector &v, int64_t image_number) { return false; } + // The latest of them + virtual std::optional GetLastWaitingImage() { return {}; } }; diff --git a/receiver/JFJochReceiverRugnuxStills.cpp b/receiver/JFJochReceiverRugnuxStills.cpp index 809e0b64d..7d95f0520 100644 --- a/receiver/JFJochReceiverRugnuxStills.cpp +++ b/receiver/JFJochReceiverRugnuxStills.cpp @@ -54,9 +54,7 @@ void JFJochReceiverRugnuxStills::OnStart(std::chrono::steady_clock::time_point r const int64_t slots = image_buffer.GetStatus().total_slots; // The frames that wait take at most half of the image buffer; the other half is for those analysed, sent from // a slot each, and a slot is kept free for each analysis thread to send with - stills_keep_free = std::min(stills_nthreads, slots / 2); - visible_max = slots / 4; - hold_arena = std::make_unique(image_buffer, slots / 2 - visible_max, stills_keep_free, + hold_arena = std::make_unique(image_buffer, slots / 2, std::min(stills_nthreads, slots / 2), experiment.GetImageBufferLocationSize()); const StartMessage start = MakeStartMessage(experiment, pixel_mask, *az_int_mapping); // The frames are shown from their arrival, on the stated geometry until the pre-pass has decided its own. @@ -73,8 +71,8 @@ void JFJochReceiverRugnuxStills::OnStart(std::chrono::steady_clock::time_point r auto analysis = std::make_unique( analysis_experiment, pixel_mask, analysis_start, indexing_thread_pool, stills_nthreads, - // What the pre-pass holds and fits on; the frames beyond it wait in the image buffer as well. - slots / 2, logger, + // What the pre-pass holds and fits on, at most: the hold full starts it earlier (OnImage) + StillsGPUAnalysis::PREPASS_MAX_IMAGES, logger, *this, live_status, true, model, deadline_s, refine_solvent); std::unique_lock ul(stills_mutex); stills = std::move(analysis); @@ -92,66 +90,32 @@ void JFJochReceiverRugnuxStills::OnImage(uint32_t id, DataMessage &message, std: CountImage(message); const size_t size = message.image.GetCompressedSize(); - // Waits for the analysis in half of the image buffer at most: in a slot of its own, where it can be seen while it - // waits (it is not sent from there), in up to half of those slots; else as its compressed bytes, packed with - // others into the rest (HoldArena) + // Waits for the analysis as its compressed bytes, packed into at most half of the image buffer (HoldArena) auto held = std::make_shared(); - HoldArena::Region region; - const auto hold = [&] { - if (visible_held.fetch_add(1) < visible_max) { - held->slot = image_buffer.GetImageSlot(stills_keep_free); - if (held->slot) { - held->release = [this] { --visible_held; }; - return true; - } - } - --visible_held; - region = hold_arena->Allocate(size); - return region.data != nullptr; - }; - bool held_ok = hold(); - while (!held_ok && image_puller.IsBlocking() && !cancelled) { + // With the hold full, the frame waits: the pre-pass starts on what is held and the analysis drains it. No frame is + // lost here; a source faster than the analysis loses frames at the card. + HoldArena::Region region = hold_arena->Allocate(size); + if (!region.data || hold_arena->Full(size)) + stills->StartPrePass(); + while (!region.data && !cancelled) { std::this_thread::sleep_for(std::chrono::milliseconds(1)); - held_ok = hold(); + region = hold_arena->Allocate(size); } - if (!held_ok) { - writer_queue_full = true; + if (!region.data) return; - } + memcpy(region.data, message.image.GetCompressed(), size); + held->release = std::move(region.release); // Not chosen (stills_downsample): written as it came, without its analysis held->analyse = StillsImageSelected(message.number, downsample, StillsGPUAnalysis::PREPASS_MAX_IMAGES); held->message = message; StampImage(held->message, image_puller.GetCurrentFifoUtilization()); - - if (held->slot) { - // In the slot as an image without analysis; the analysis reads the image where it is in the slot. - auto slot_buffer = static_cast(held->slot->GetImage()); - CBORStream2Serializer serializer(slot_buffer, experiment.GetImageBufferLocationSize()); - held->message.image = CompressedImage(nullptr, 0, message.image.GetWidth(), message.image.GetHeight(), - message.image.GetMode(), message.image.GetCompressionAlgorithm(), - message.image.GetChannel()); - serializer.SerializeImage(held->message); - const size_t image_offset = serializer.GetImageAppendOffset(); - if (image_offset + size + 32 >= static_cast(experiment.GetImageBufferLocationSize())) { - logger.Error("Dropping image {} - metadata {} B + image {} B do not fit in buffer slot {} B", message.number, - image_offset, size, experiment.GetImageBufferLocationSize()); - return; - } - memcpy(slot_buffer + image_offset, message.image.GetCompressed(), size); - serializer.AppendImage(size); - held->message.image = CompressedImage(slot_buffer + image_offset, size, message.image.GetWidth(), - message.image.GetHeight(), message.image.GetMode(), - message.image.GetCompressionAlgorithm(), message.image.GetChannel()); - held->slot->SetImageNumber(message.number); - held->slot->SetImageSize(serializer.GetBufferSize()); - held->slot->SetIndexed(false); - held->slot->ReadyToSend(); - } else { - memcpy(region.data, message.image.GetCompressed(), size); - held->release = std::move(region.release); - held->message.image = CompressedImage(region.data, size, message.image.GetWidth(), message.image.GetHeight(), - message.image.GetMode(), message.image.GetCompressionAlgorithm(), - message.image.GetChannel()); + held->message.image = CompressedImage(region.data, size, message.image.GetWidth(), message.image.GetHeight(), + message.image.GetMode(), message.image.GetCompressionAlgorithm(), + message.image.GetChannel()); + { + // Seen while it waits (GetWaitingImage): the message as it came, as the analysis changes its own + std::unique_lock ul(waiting_mutex); + waiting[message.number] = Waiting{.held = held, .message = held->message}; } stills->Hold(held); } @@ -230,6 +194,10 @@ ZeroCopyReturnValue *JFJochReceiverRugnuxStills::AnalysedImageSlot() { } void JFJochReceiverRugnuxStills::SendAnalysedImage(DataMessage &message, const AzimuthalIntegrationProfile &profile) { + { + std::unique_lock ul(waiting_mutex); + waiting.erase(message.number); + } try { const auto status = image_buffer.GetSlotStatus(); message.receiver_buf_available = status.available_slots; @@ -257,6 +225,32 @@ void JFJochReceiverRugnuxStills::SendAnalysedImage(DataMessage &message, const A } } +std::optional JFJochReceiverRugnuxStills::GetLastWaitingImage() { + std::unique_lock ul(waiting_mutex); + // A frame the analysis let go of without sending it (a failed setup) is no longer there + while (!waiting.empty() && waiting.rbegin()->second.held.expired()) + waiting.erase(std::prev(waiting.end())); + if (waiting.empty()) + return {}; + return waiting.rbegin()->first; +} + +bool JFJochReceiverRugnuxStills::GetWaitingImage(std::vector &v, int64_t image_number) { + std::unique_lock ul(waiting_mutex); + const auto it = waiting.find(image_number); + if (it == waiting.end()) + return false; + // The frame's bytes in the hold stay while this copy is made + const auto held = it->second.held.lock(); + if (!held) + return false; + v.resize(experiment.GetImageBufferLocationSize()); + CBORStream2Serializer serializer(v.data(), v.size()); + serializer.SerializeImage(it->second.message); + v.resize(serializer.GetBufferSize()); + return true; +} + void JFJochReceiverRugnuxStills::AddToEndMessage(EndMessage &message) { JFJochReceiverStream::AddToEndMessage(message); // A failure here costs the end message the analysis only: it goes out as the receiver made it. diff --git a/receiver/JFJochReceiverRugnuxStills.h b/receiver/JFJochReceiverRugnuxStills.h index 57d5c09ee..395a4bbd3 100644 --- a/receiver/JFJochReceiverRugnuxStills.h +++ b/receiver/JFJochReceiverRugnuxStills.h @@ -3,6 +3,7 @@ #pragma once +#include #include #include #include @@ -22,13 +23,17 @@ class JFJochReceiverRugnuxStills : public JFJochReceiverStream, public StillsSin IndexerThreadPool *const indexing_thread_pool; const int64_t stills_nthreads; - // The frames waiting for the analysis take at most half of the image buffer's slots: a quarter as a slot each, - // the rest packed as their compressed bytes (a frame is a fraction of a slot: 1.5 MB of a 24 MB slot on a 9M - // detector, and the pre-pass holds every frame that arrives before it is over) - int64_t stills_keep_free = 0; // slots frames do not take, for the analysis threads to send with - int64_t visible_max = 0; - std::atomic visible_held = 0; + // The frames waiting for the analysis, packed as their compressed bytes into at most half of the image buffer's + // slots (a frame is a fraction of a slot: 1.5 MB of a 24 MB slot on a 9M detector, and the pre-pass holds every + // frame that arrives before it is over); a slot is kept free for each analysis thread to send with std::unique_ptr hold_arena; + // The frames waiting, by number, as they came, to be seen while they wait + struct Waiting { + std::weak_ptr held; + DataMessage message; + }; + std::mutex waiting_mutex; + std::map waiting; std::mutex stills_mutex; bool cut = false; @@ -64,4 +69,7 @@ public: IndexerThreadPool *indexing_thread_pool = nullptr, int64_t downsample = 1); ~JFJochReceiverRugnuxStills() override; + + bool GetWaitingImage(std::vector &v, int64_t image_number) override; + std::optional GetLastWaitingImage() override; }; diff --git a/receiver/JFJochReceiverService.cpp b/receiver/JFJochReceiverService.cpp index 50d9d892d..709849ba5 100644 --- a/receiver/JFJochReceiverService.cpp +++ b/receiver/JFJochReceiverService.cpp @@ -424,20 +424,29 @@ void JFJochReceiverService::GetStartMessageFromBuffer(std::vector &v) { image_buffer.GetStartMessage(v); } +// The image buffer, then the frames the receiver holds and has not sent yet (live stills, waiting for the analysis) bool JFJochReceiverService::GetImageFromBuffer(std::vector &v, int64_t image_number) { - return image_buffer.GetImage(v, image_number); + std::unique_lock ul(state_mutex); // the receiver is replaced at a start + if (receiver && image_number == ImageBuffer::MaxImage) { + const auto waiting = receiver->GetLastWaitingImage(); + if (waiting && *waiting > image_buffer.GetStatus().max_image_number) + image_number = *waiting; + } + if (image_buffer.GetImage(v, image_number)) + return true; + return receiver && (image_number != ImageBuffer::MaxImage) && receiver->GetWaitingImage(v, image_number); } std::string JFJochReceiverService::GetJPEGFromBuffer(const PreviewImageSettings &settings, int64_t image_number) { std::vector cbor_image; - if (!image_buffer.GetImage(cbor_image, image_number)) + if (!GetImageFromBuffer(cbor_image, image_number)) return {}; return preview_image.GenerateImage(settings, cbor_image); } std::string JFJochReceiverService::GetTIFFFromBuffer(int64_t image_number) { std::vector cbor_image; - if (!image_buffer.GetImage(cbor_image, image_number)) + if (!GetImageFromBuffer(cbor_image, image_number)) return {}; return PreviewImage::GenerateTIFF(cbor_image); } diff --git a/receiver/StillsGPUAnalysis.h b/receiver/StillsGPUAnalysis.h index fd85e4711..cbb2f3dc1 100644 --- a/receiver/StillsGPUAnalysis.h +++ b/receiver/StillsGPUAnalysis.h @@ -67,6 +67,8 @@ public: ~StillsGPUAnalysis(); void Hold(const std::shared_ptr &image); + // The frames held are all the pre-pass gets (the end of the collection, or no room for more): it starts on them + void StartPrePass(); // No frame comes after this: every frame is analysed before it returns. Throws if the setup after the pre-pass failed. void Finish(); // After Finish, once everything is written; without it the outcome is reported when the analysis goes @@ -159,7 +161,6 @@ private: void ModelThread(); void PublishModel(const ModelStepResult &result, const std::string &title); - void StartPrePass(); void PrePassThread(); void AnalysisThread(); void MergeThread(); diff --git a/tests/JFJochReceiverRugnuxTest.cpp b/tests/JFJochReceiverRugnuxTest.cpp index 167167439..bc3b7cc46 100644 --- a/tests/JFJochReceiverRugnuxTest.cpp +++ b/tests/JFJochReceiverRugnuxTest.cpp @@ -220,7 +220,7 @@ TEST_CASE("JFJochReceiverRugnux_Stills", "[JFJochReceiverRugnux]") { } TEST_CASE("JFJochReceiverRugnux_Stills_ImagesVisibleDuringPrePass", "[JFJochReceiverRugnux]") { - // A frame held for the pre-pass can be seen in the image buffer as it came, with a start message on the stated + // A frame held for the pre-pass can be seen through the image routes as it came, with a start message on the stated // geometry; once analysed, the copy with the analysis is the only one there. The writer gets each image once. Logger logger(Catch::getResultCapture().getCurrentTestName()); RegisterHDF5Filter(); @@ -263,7 +263,8 @@ TEST_CASE("JFJochReceiverRugnux_Stills_ImagesVisibleDuringPrePass", "[JFJochRece } REQUIRE(service.GetImageFromBuffer(cbor, ImageBuffer::MaxImage)); CHECK(CBORStream2Deserialize(cbor)->data_message->number == held - 1); - CHECK(service.GetImageBufferStatus().sending_slots == held); + // They wait in the receiver's hold, not as images of the buffer: none is in a slot to be sent + CHECK(service.GetImageBufferStatus().sending_slots == 0); // Nothing goes to the writer before the pre-pass CHECK(pusher.Events().empty()); @@ -348,10 +349,9 @@ TEST_CASE("JFJochReceiverRugnux_Stills_CancelDuringRun", "[JFJochReceiverRugnux] PixelMask mask(x); Stream stream(x, images); - // Twelve slots: the pre-pass ends on six frames, and the analysis starts with most of the run to come. - const size_t buffer_MiB = 12 * x.GetImageBufferLocationSize() / (1024 * 1024) + 1; - const int64_t given = 8; - stream.Frames(0, given); + // Four slots: the pre-pass starts once the two the frames wait in are full, and the analysis starts with most of + // the run to come. The frames are given one by one until it does. + const size_t buffer_MiB = 4 * x.GetImageBufferLocationSize() / (1024 * 1024) + 1; RecordingPusher pusher; AcquisitionDeviceGroup group; @@ -362,6 +362,16 @@ TEST_CASE("JFJochReceiverRugnux_Stills_CancelDuringRun", "[JFJochReceiverRugnux] service.RugnuxLive(true, std::make_shared(), 4, 60); service.Start(x, mask, nullptr, stream.puller); + int64_t given = 0; + const auto holding = [&] { + const auto s = service.GetRugnuxStatus(); + return !s.stills || s.stills->prepass == RugnuxLivePrePass::Holding; + }; + while (holding() && given < images - 1) { + stream.Frames(given++, 1); + std::this_thread::sleep_for(std::chrono::milliseconds(100)); + } + REQUIRE(given < images - 1); WaitForStatus(service, [](const RugnuxLiveSnapshot &s) { return s.stills && s.stills->prepass == RugnuxLivePrePass::Done && s.stills->images_analysed > 0; }); @@ -369,6 +379,7 @@ TEST_CASE("JFJochReceiverRugnux_Stills_CancelDuringRun", "[JFJochReceiverRugnux] const auto out = service.Stop(); CHECK(out.status.cancelled); + CHECK(out.status.images_collected == given); CHECK(out.status.images_sent == given); CHECK(pusher.Events() == std::vector{"start", "image", "end"}); const auto live = service.GetRugnuxStatus(); @@ -636,16 +647,16 @@ TEST_CASE("JFJochReceiverRugnux_Stills_ZMQWriterDown", "[JFJochReceiverRugnux]") } TEST_CASE("JFJochReceiverRugnux_Stills_BufferFullDuringPrePass", "[JFJochReceiverRugnux]") { - // Forty frames, all there before the pre-pass ends, and twelve slots in the image buffer. + // More frames than half of a twelve-slot image buffer holds, all there before the pre-pass ends. The frames that + // wait take at most half of the buffer: past it, a frame waits, the pre-pass starts on what is held and the + // analysis drains it. Every frame is written. Logger logger(Catch::getResultCapture().getCurrentTestName()); RegisterHDF5Filter(); - const int64_t images = 40; + const int64_t images = 200; DiffractionExperiment x = StillsExperiment(images); PixelMask mask(x); Stream stream(x, images); - stream.Frames(0, images); - stream.End(); const size_t buffer_MiB = 12 * x.GetImageBufferLocationSize() / (1024 * 1024) + 1; @@ -656,16 +667,15 @@ TEST_CASE("JFJochReceiverRugnux_Stills_BufferFullDuringPrePass", "[JFJochReceive service.Indexing(x.GetIndexingSettings()); service.RugnuxLive(true, nullptr, 4, 60); + stream.Frames(0, images); + stream.End(); service.Start(x, mask, nullptr, stream.puller); const auto out = service.Stop(); // No deadlock, and the end message goes out. CHECK(!out.status.cancelled); CHECK(pusher.Events() == std::vector{"start", "image", "end"}); - - // A frame that finds no free slot waits in a copy of its own, and is written. CHECK(out.status.images_collected == images); - CHECK(out.efficiency == 1.0f); CHECK(out.status.images_sent == images); CHECK(!out.writer_queue_full_warning); CHECK(out.scan_result.images.size() == out.status.images_sent); From a152dd9f6398b98ec734a89f69e5477e387494f3 Mon Sep 17 00:00:00 2001 From: Filip Leonarski Date: Wed, 18 Nov 2026 20:07:24 +0100 Subject: [PATCH 39/41] ImagePuller: IsBlocking removed, nothing asks it any more Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01HVeDQrPqZ52Tp6rzzZGxf3 --- image_puller/ImagePuller.h | 3 --- receiver/FPGAImagePuller.h | 2 -- 2 files changed, 5 deletions(-) diff --git a/image_puller/ImagePuller.h b/image_puller/ImagePuller.h index 5c9935730..ad065a0fd 100644 --- a/image_puller/ImagePuller.h +++ b/image_puller/ImagePuller.h @@ -75,9 +75,6 @@ public: virtual bool SendAck(const PullerAckMessage &) { return false; } virtual void Disconnect() = 0; - - // The source waits for the receiver rather than lose an image: the receiver waits for room instead of dropping it - virtual bool IsBlocking() const { return false; } }; diff --git a/receiver/FPGAImagePuller.h b/receiver/FPGAImagePuller.h index e2d850644..b87a61f80 100644 --- a/receiver/FPGAImagePuller.h +++ b/receiver/FPGAImagePuller.h @@ -76,8 +76,6 @@ public: ~FPGAImagePuller() override; void Disconnect() override {} - // Its images wait for the receiver, so the receiver's hold waits as well (JFJochReceiverRugnuxStills) - bool IsBlocking() const override { return true; } // The cards finish: what they have got still comes, then the end message. void StopCards(); From d279137b2ec3143852497773fadc3e22b3058f03 Mon Sep 17 00:00:00 2001 From: Filip Leonarski Date: Wed, 18 Nov 2026 20:29:29 +0100 Subject: [PATCH 40/41] FPGAImagePuller: images the cards never got to are skipped; the puller always stops An image whose frames no card got to (all cards finished, every one's fastest frame before the image's first) is now let go at once, as JFJochReceiverFPGA does, instead of being assembled from missing modules: an abort early in a long run took minutes to work through the rest while Stop() waited, and a silent end with fewer frames than asked for left the receiver without messages long enough to declare the end message lost. JFJochReceiverService::FinalizeMeasurement stops the puller even when the receiver ends with an error, so its threads do not hold the cards' buffers, and the cards stay armed, until the next run; the receiver's error is rethrown first. Nits: WaitForFrame's comment no longer refers to the removed cross-card give-up; emplace for try_emplace; jfjoch_fpga_stills_test no longer prints the always-0 dropped count; docs/TOOLS.md names the writer exception (an analysed image without an image-buffer slot within the wait is not written, writer_queue_full). Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01HVeDQrPqZ52Tp6rzzZGxf3 --- docs/TOOLS.md | 11 +++++++---- receiver/FPGAImagePuller.cpp | 21 ++++++++++++++++++--- receiver/FPGAImagePuller.h | 2 ++ receiver/JFJochReceiverService.cpp | 12 ++++++++++-- tools/jfjoch_fpga_stills_test.cpp | 8 +++----- 5 files changed, 40 insertions(+), 14 deletions(-) diff --git a/docs/TOOLS.md b/docs/TOOLS.md index 92b53c069..af32245a7 100644 --- a/docs/TOOLS.md +++ b/docs/TOOLS.md @@ -101,12 +101,15 @@ jfjoch_fpga_stills_test [-i ] [-s ] [-N ] [-B ] [-C apply here) and prints the mapping. These are the first ones of the file, cycled for the whole run of `-i` images (default: as many as the file has). **Images repeat**, so throughput, latency, spots per image and indexing rate are meaningful, the merge and its statistics are not. -- One collection per invocation, as fast as it goes. Nothing on the host discards an image: `FPGAImagePuller` - waits for room in its queue to the receiver and the stills receiver for room in the image buffer, so the card +- One collection per invocation, as fast as it goes. Nothing on the host discards an image on its way to the + analysis: `FPGAImagePuller` waits for room in its queue to the receiver and the stills receiver for room in the + image buffer, so the card keeps its frames, its host writer waits for host buffers and the stall reaches the internal generator through the card's AXI-stream back-pressure (the generator sits before the network stack; a real detector's UDP - packets would be lost at that point instead, the only place frames are lost). The card's own count of the - cycles it waited for host buffers is printed per card: how long the chain behind it held the source. + packets would be lost at that point instead). The one exception is the writer: an analysed image that finds + no image-buffer slot for the writer within the wait is not written and is counted (`writer_queue_full`). The + card's own count of the cycles it waited for host buffers is printed per card: how long the chain behind it + held the source. - The cards' generators run free, each as fast as its modules' bandwidth allows, so cards with different numbers of modules (a 9M on 4 cards: 5, 5, 4, 4) run at different speeds - unlike the modules of a detector, which a common trigger keeps together; the run then goes at the pace of the slowest card. diff --git a/receiver/FPGAImagePuller.cpp b/receiver/FPGAImagePuller.cpp index 5b0c1c791..94add9ee9 100644 --- a/receiver/FPGAImagePuller.cpp +++ b/receiver/FPGAImagePuller.cpp @@ -118,8 +118,8 @@ void FPGAImagePuller::AcquireThread(uint16_t data_stream, const PixelMask &mask, } } -// Polled: a dead card has to be noticed from the other cards' frames. A frame given up on that comes later is below -// the device's slowest frame then (MissingAfterFrames), and the device returns its buffer itself. +// Polled: a card that fails or finishes ends the wait. A frame given up on that comes later is below the device's +// slowest frame then (MissingAfterFrames), and the device returns its buffer itself. bool FPGAImagePuller::WaitForFrame(uint16_t data_stream, uint16_t module_number, int64_t frame) { const auto &counters = devices[data_stream].Counters(); // A frame is complete once the module is two further on, as in JFJochReceiverFPGA @@ -130,6 +130,15 @@ bool FPGAImagePuller::WaitForFrame(uint16_t data_stream, uint16_t module_number, return counters.IsAnyPacketCollected(frame, module_number); } +bool FPGAImagePuller::CardsFinishedBefore(int64_t frame) const { + for (int d = 0; d < experiment.GetDataStreamsNum(); d++) { + const auto &counters = devices[d].Counters(); + if (!counters.IsAcquisitionFinished() || (static_cast(counters.GetFastestFrameNumber()) >= frame)) + return false; + } + return true; +} + void FPGAImagePuller::ImageThread() { // One image of its own, assembled and compressed here FrameTransformation transformation(experiment); @@ -140,6 +149,12 @@ void FPGAImagePuller::ImageThread() { summation.emplace_back(std::make_unique(experiment)); try { for (int64_t image = next_to_take++; image < experiment.GetImageNum() && !failed; image = next_to_take++) { + // The cards are through and none got as far as this image (a cancel, or fewer frames than asked for): + // it will not come, and is not assembled from missing modules either - as JFJochReceiverFPGA + if (CardsFinishedBefore(image * host_summation)) { + Emit(image, std::nullopt); + continue; + } ImageMetadata metadata(experiment); auto take_module = [&](const DeviceOutput *output, int d, int m) { metadata.Process(output); @@ -215,7 +230,7 @@ void FPGAImagePuller::ImageThread() { // Whichever thread finishes the image next in line lets it, and those waiting behind it, out. void FPGAImagePuller::Emit(int64_t image_number, std::optional output) { std::unique_lock ul(order_mutex); - images_done.try_emplace(image_number, std::move(output)); + images_done.emplace(image_number, std::move(output)); for (auto it = images_done.begin(); (it != images_done.end()) && (it->first == next_image); it = images_done.erase(it), next_image++) { if (it->second) { diff --git a/receiver/FPGAImagePuller.h b/receiver/FPGAImagePuller.h index e2d850644..d04f9dfdd 100644 --- a/receiver/FPGAImagePuller.h +++ b/receiver/FPGAImagePuller.h @@ -66,6 +66,8 @@ private: // False where the module is missing from the frame bool WaitForFrame(uint16_t data_stream, uint16_t module_number, int64_t frame); + // Every card has finished, all of them before this frame + bool CardsFinishedBefore(int64_t frame) const; void Emit(int64_t image_number, std::optional output); // Waits for room in the queue, as long as the receiver takes from it: after a cancel it no longer does void Put(const ImagePullerOutput &output); diff --git a/receiver/JFJochReceiverService.cpp b/receiver/JFJochReceiverService.cpp index 22beb46c2..2dc5fe7d2 100644 --- a/receiver/JFJochReceiverService.cpp +++ b/receiver/JFJochReceiverService.cpp @@ -83,15 +83,23 @@ void JFJochReceiverService::FinalizeMeasurementChangeState() { } void JFJochReceiverService::FinalizeMeasurement() { + // The puller is stopped however the receiver ended: its threads hold the cards' buffers otherwise + std::exception_ptr error; try { receiver->StopReceiver(); + } catch (...) { + error = std::current_exception(); + } + try { if (fpga_puller) fpga_puller->Stop(); } catch (...) { - FinalizeMeasurementChangeState(); - throw; + if (!error) + error = std::current_exception(); } FinalizeMeasurementChangeState(); + if (error) + std::rethrow_exception(error); } std::optional JFJochReceiverService::GetStatus() { diff --git a/tools/jfjoch_fpga_stills_test.cpp b/tools/jfjoch_fpga_stills_test.cpp index f9f441b29..6ff5d4b81 100644 --- a/tools/jfjoch_fpga_stills_test.cpp +++ b/tools/jfjoch_fpga_stills_test.cpp @@ -183,8 +183,7 @@ bool RunDataset(Logger &logger, AcquisitionDeviceGroup &aq_devices, const std::s aq_devices[i].Counters().IsAcquisitionFinished() ? " done" : ""); // Where a run stands, so that one that stops shows which part waits if (const auto st = service.GetStatus()) - line += fmt::format(" receiver: collected {} sent {} dropped {}", st->images_collected, - st->images_sent, st->images_dropped); + line += fmt::format(" receiver: collected {} sent {}", st->images_collected, st->images_sent); const auto live = service.GetRugnuxStatus(); if (live.stills) line += fmt::format(" stills: held {} analysed {} pre-pass {}", live.stills->images_held, @@ -217,9 +216,8 @@ bool RunDataset(Logger &logger, AcquisitionDeviceGroup &aq_devices, const std::s const double delivery_s = live.last_image_s.value_or(0); const double delivered_hz = (delivery_s > 0) ? static_cast(output.status.images_collected - 1) / delivery_s : 0; - logger.Info("Images expected {} collected {} sent {} dropped {} efficiency {:.4f}", - x.GetImageNum(), output.status.images_collected, output.status.images_sent, - output.status.images_dropped, output.efficiency); + logger.Info("Images expected {} collected {} sent {} efficiency {:.4f}", + x.GetImageNum(), output.status.images_collected, output.status.images_sent, output.efficiency); logger.Info("Delivered {:.1f} Hz (first to last image {:.2f} s)", delivered_hz, delivery_s); logger.Info("Sustained {:.1f} Hz (images / wall time {:.2f} s, start to analysis done) CPU {:.1f} s = {:.1f} cores" " max resident memory {:.1f} GiB", From 4ad1814af4f1c91979edb307abf5060aa600ee62 Mon Sep 17 00:00:00 2001 From: Filip Leonarski Date: Wed, 18 Nov 2026 20:29:29 +0100 Subject: [PATCH 41/41] FPGAImagePuller tests: abort of a long run, cards stopped while stalled, receiver error AbortLargeRun: 1M images of 8 modules, cancelled after a second, ends within 30 s (about 30 s and a timeout before the fix, about 5 s after). StopCardsWhileStalled: nobody reads, the queue full and the card waiting for buffers when StopCards() comes; every image the card got (195) is delivered, in order, then the end message. ReceiverErrorStopsPuller: the writer refuses the start message; Stop() throws and the card is released (it stayed armed before the fix). CollectingPusher can refuse the start message for that. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01HVeDQrPqZ52Tp6rzzZGxf3 --- tests/FPGAImagePullerTest.cpp | 103 ++++++++++++++++++++++++++++++++++ 1 file changed, 103 insertions(+) diff --git a/tests/FPGAImagePullerTest.cpp b/tests/FPGAImagePullerTest.cpp index 2ca220e77..0739d52f8 100644 --- a/tests/FPGAImagePullerTest.cpp +++ b/tests/FPGAImagePullerTest.cpp @@ -42,8 +42,11 @@ namespace { std::vector sequence; EndMessage end; std::chrono::milliseconds delay{0}; + bool fail_start = false; void StartDataCollection(StartMessage &) override { + if (fail_start) + throw JFJochException(JFJochExceptionCategory::ZeroMQ, "writer refused the start message"); std::unique_lock ul(m); sequence.emplace_back("start"); } @@ -547,6 +550,106 @@ TEST_CASE("FPGAImagePuller_SilentEndDeliversAll", "[FPGAImagePuller]") { CHECK(pusher.sequence.back() == "end"); } +// An abort early in a long run ends in bounded time: the images the cards never got to are not assembled +// one by one. Run on a thread of its own, so that a hang fails the test instead of stopping the run. +TEST_CASE("FPGAImagePuller_AbortLargeRun", "[FPGAImagePuller]") { + auto x = Base(DetJF(8), 1000000, 1); + x.Conversion(); + x.Compression(CompressionAlgorithm::BSHUF_LZ4); + + auto devices = std::make_shared(Devices(x)); + auto logger = std::make_shared("FPGAImagePuller_AbortLargeRun"); + auto mask = std::make_shared(x); + auto puller = std::make_shared(x, *mask, nullptr, *devices, *logger, 4); + std::this_thread::sleep_for(1s); + + auto stopped = std::make_shared>(); + auto done = stopped->get_future(); + std::thread([puller, devices, logger, mask, stopped] { + puller->Cancel(); + try { + puller->Stop(); + } catch (...) {} + stopped->set_value(); + }).detach(); + REQUIRE(done.wait_for(30s) == std::future_status::ready); +} + +// The cards are stopped while they wait for the host (nobody reads, the queue is full): every image they hold +// still comes, in order, then the end message. +TEST_CASE("FPGAImagePuller_StopCardsWhileStalled", "[FPGAImagePuller]") { + constexpr int64_t images = 1000; + auto x = Base(DetJF(1), images, 1); + x.Conversion(); + x.Compression(CompressionAlgorithm::BSHUF_LZ4); + + auto devices = Devices(x); + Logger logger("FPGAImagePuller_StopCardsWhileStalled"); + PixelMask mask(x); + const JFCalibration calib = Calibration(x); + FPGAImagePuller puller(x, mask, &calib, devices, logger, 2); + + // The queue full, then the card waiting for host buffers + const auto t0 = std::chrono::steady_clock::now(); + while (puller.GetCurrentFifoUtilization() < FPGAImagePuller::Queue && std::chrono::steady_clock::now() - t0 < 60s) + std::this_thread::sleep_for(10ms); + REQUIRE(puller.GetCurrentFifoUtilization() >= FPGAImagePuller::Queue); + std::this_thread::sleep_for(1s); + const auto fastest = devices[0].Counters().GetFastestFrameNumber(); + std::this_thread::sleep_for(500ms); + REQUIRE(devices[0].Counters().GetFastestFrameNumber() == fastest); + REQUIRE(!devices[0].Counters().IsAcquisitionFinished()); + puller.StopCards(); + + std::vector numbers; + bool end = false; + while (!end && std::chrono::steady_clock::now() - t0 < 120s) { + const auto m = puller.PollImage(10ms); + if (!m) + continue; + if (m->cbor->data_message) + numbers.push_back(m->cbor->data_message->number); + end = m->cbor->end_message.has_value(); + } + CHECK(end); + REQUIRE_NOTHROW(puller.Stop()); + + int64_t on_card = 0; + for (int64_t f = 0; f < images; f++) + if (devices[0].Counters().IsAnyPacketCollected(f, 0)) + on_card++; + std::cout << "cards stopped while stalled: " << numbers.size() << " images delivered, " << on_card + << " on the card" << std::endl; + CHECK(on_card >= static_cast(FPGAImagePuller::Queue)); + CHECK(on_card < images); + REQUIRE(static_cast(numbers.size()) == on_card); + for (size_t i = 0; i < numbers.size(); i++) + CHECK(numbers[i] == static_cast(i)); +} + +// The receiver ends on an error (the writer refuses the start message) while the puller still has images: the +// puller is stopped with it and the card released, not left armed until the next run. +TEST_CASE("FPGAImagePuller_ReceiverErrorStopsPuller", "[FPGAImagePuller]") { + auto x = Base(DetJF(1), 1000, 1); + x.Conversion(); + x.Compression(CompressionAlgorithm::BSHUF_LZ4); + + auto devices = Devices(x); + Logger logger("FPGAImagePuller_ReceiverError"); + CollectingPusher pusher; + pusher.fail_start = true; + JFJochReceiverService service(devices, logger, pusher, 256); + service.NumThreads(1).SetSpotFindingSettings(Spots()); + service.FPGAImagePullerSettings(true); + + PixelMask mask(x); + const JFCalibration calib = Calibration(x); + service.Start(x, mask, &calib); + CHECK_THROWS(service.Stop()); + CHECK(devices[0].Counters().IsAcquisitionFinished()); + CHECK(devices[0].Counters().GetFastestFrameNumber() < 999); +} + // A module frame missing in the middle, and a module that dies: the images keep coming with no help // from the end of the run, and the missing module is filled, as in JFJochReceiverFPGA. TEST_CASE("FPGAImagePuller_MissingModule", "[FPGAImagePuller]") {