Files
leonarski_fandClaude Opus 5.5 2250e4019c Merge rc184-2 into rc185: stream receivers, Rugnux live stills, puller, pedestal and dark-mask receivers, card mock
The rc184-2 receiver architecture is kept; what rc184 added since rc183 is carried into it:

- JFJochReceiverRugnuxRotation: the live host budget is nine tenths of the machine's total less the
  image buffer and the margin, at most the machine's budget (was the budget less both); the pinned
  host pool is released after the end message, in MeasurementThread, not in RugnuxThread.
- StillsGPUAnalysis: the escalating pre-pass is bounded by PREPASS_MAX_IMAGES (4 x PREPASS_IMAGES)
  as well as by half the image buffer, and frames arriving during a run do not make the next one
  larger than that. The other live-stills changes of rc184 (pre-pass holding until the geometry can
  be fitted, geometry fixed when it ends, fixed q range, no running refinement) were already in
  rc184-2.
- IndexAndRefine, RotationIndexer, rugnux: rc184's versions, with rc184-2's receiver-owned indexer.
- Tests: FPGAIntegrationTest.cpp stays removed (generator memory check is in
  MockAcquisitionDeviceTest, pixel-sum parity in ImagePreprocessorPixelSumTest); the FPGA live-stills
  tests of JFJochReceiverProcessingTest are covered by JFJochReceiverRugnuxTest (pre-pass cancel,
  ZeroMQ writer, writer down).
- Docs: rc184's text plus rc184-2's receiver table, broker diagram, stream and test notes;
  NumberTextField and CHANGELOG as in rc184.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HVeDQsU5a8AJUdJPgWevAK
2026-11-11 08:58:28 +01:00

161 lines
7.1 KiB
C++

// SPDX-FileCopyrightText: 2026 Filip Leonarski, Paul Scherrer Institute <filip.leonarski@psi.ch>
// SPDX-License-Identifier: GPL-3.0-only
#pragma once
#include <array>
#include <condition_variable>
#include <exception>
#include <future>
#include <latch>
#include <map>
#include <memory>
#include <mutex>
#include <vector>
#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"
#include "../rugnux/ModelStep.h"
struct StillsSetup {
DiffractionExperiment experiment;
PixelMask mask;
std::unique_ptr<AzimuthalIntegrationMapping> mapping;
};
// What StillsGPUAnalysis needs from its owner (JFJochReceiverRugnuxStills).
class StillsSink {
public:
virtual ~StillsSink() = default;
// The pre-pass is over, no frame is analysed before this returns: the owner sends the start message.
virtual void StillsReady(const StillsSetup &setup) = 0;
// A frame is analysed; called from the analysis threads.
virtual void SendAnalysedImage(DataMessage &message, const AzimuthalIntegrationProfile &profile) = 0;
virtual SpotFindingSettings AnalysisSettings() = 0;
// The setup after the pre-pass failed, StillsReady included.
virtual void StillsSetupFailed(const JFJochException &error) = 0;
};
// Serial frames analysed on the GPU at the geometry of a pre-pass (fixed from there on), and merged beside the analysis
class StillsGPUAnalysis {
public:
// Enough frames for the distance to be refined at a serial hit rate; they wait in the image buffer
constexpr static int64_t PREPASS_IMAGES = 500;
// The most a pre-pass run on held frames takes: the last run stays short, so the frames arriving meanwhile flow
constexpr static int64_t PREPASS_MAX_IMAGES = 4 * PREPASS_IMAGES;
constexpr static std::array<double, 2> CHECKPOINTS = {0.5, 0.75};
constexpr static int MERGE_THREADS = 8;
// `start`: the collection's start message, as it would be sent without the pre-pass.
StillsGPUAnalysis(const DiffractionExperiment &experiment, const PixelMask &mask, const StartMessage &start,
IndexerThreadPool *indexing_thread_pool, int64_t nthreads, int64_t max_held, Logger &logger,
StillsSink &sink, RugnuxLiveStatus &status, bool merge = true,
std::shared_ptr<const RugnuxModel> model = nullptr, double deadline_s = 0);
~StillsGPUAnalysis();
void Hold(const std::shared_ptr<HeldImage> &image);
// 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
void ReportOutcome();
// POST /cancel: the model step stops where it is, as at the deadline, and the frames are still analysed and merged.
void Cut(const std::string &reason);
// After Finish.
[[nodiscard]] std::optional<UnitCell> 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<StillsMergeOutput> &GetMerged() const;
[[nodiscard]] const DiffractionExperiment &GetMergeExperiment() const;
// The model step on the merge of the collection, where one was made.
[[nodiscard]] const std::optional<ModelStepResult> &GetModel() const;
// The cell, geometry and merged data, in the model's frame where a model was placed
void FillEndMessage(EndMessage &message) const;
private:
const DiffractionExperiment &experiment;
const PixelMask &mask;
const StartMessage start;
IndexerThreadPool *indexing_thread_pool;
Logger &logger;
StillsSink &sink;
RugnuxLiveStatus &status;
const bool merge_frames;
std::mutex live_mutex;
RugnuxLiveStills live;
std::chrono::steady_clock::time_point ready_time;
void Publish();
std::optional<std::pair<RugnuxLiveState, std::string>> outcome; // kept by Finish for ReportOutcome
StillsSetup setup;
std::unique_ptr<IndexAndRefine> indexer;
std::mutex prepass_mutex;
std::condition_variable prepass_cv;
enum class PrePassState {Holding, Closing, Over}; // Closing: what is held is all there will be
PrePassState prepass_state = PrePassState::Holding;
std::map<int64_t, std::shared_ptr<HeldImage>> 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 hold_limit; // the frames the pre-pass holds and fits on, at most
ThreadSafeFIFO<std::shared_ptr<HeldImage>> queue;
std::future<void> prepass_future;
std::vector<std::future<void>> analysis_futures;
// The frames analysed, by number, for the merge (-1 after the last); it takes their outcomes from the indexer.
ThreadSafeFIFO<int64_t> merge_queue;
std::unique_ptr<StillsLiveMerge> merge; // after the indexer: its reflections are in the indexer's arena
DiffractionExperiment merge_experiment;
std::optional<StillsMergeOutput> merged;
std::future<void> merge_future;
// Placed against each merge, mapped and refined on a thread of its own; Finish waits until deadline_s, then cuts it
const std::shared_ptr<const RugnuxModel> model;
const double deadline_s;
std::string model_left_out; // why the model is left out; set by the merge thread before any step
struct ModelJob {
std::vector<MergedReflection> merged;
std::vector<float> shells; // the merge statistics' shell bounds
std::string title;
bool final = false;
bool cut = false;
};
std::mutex model_mutex;
std::condition_variable model_cv;
std::optional<ModelJob> model_next;
std::atomic<bool> step_cut{false}; // the step running is cut
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
std::optional<ModelStepResult> model_placed; // the last step that placed the model, for the next to start from
std::optional<ModelStepResult> model_final;
std::future<void> model_future;
// The step on `out`, the merge of `title` (its reflections moved out, but for the final one).
void SubmitModel(StillsMergeOutput &out, const std::string &title, bool final);
void StopModel(bool cut);
void ModelThread();
void PublishModel(const ModelStepResult &result, const std::string &title);
void StartPrePass();
void PrePassThread();
void AnalysisThread();
void MergeThread();
void PublishMerge(const StillsMergeOutput &out, const std::string &title);
};