// SPDX-FileCopyrightText: 2024 Filip Leonarski, Paul Scherrer Institute <filip.leonarski@psi.ch>
// SPDX-License-Identifier: GPL-3.0-only

#include <algorithm>
#include <atomic>
#include <chrono>
#include <cmath>
#include <cstdio>
#include <cstdlib>
#include <cstring>
#include <csignal>
#include <filesystem>
#include <fstream>
#include <future>
#include <optional>
#include <getopt.h>
#include <iostream>
#include <limits>
#include <sstream>
#include <stdexcept>
#include <string>
#include <system_error>
#include <thread>
#include <type_traits>
#include <vector>

#include "../reader/JFJochHDF5Reader.h"
#include "../reader/JFJochCBFReader.h"
#include "../reader/JFJochMarCCDReader.h"
#include "../reader/JFJochSMVReader.h"
#include "../reader/JFJochCrystFELReader.h"
#include "../reader/JFJochXTCReader.h"
#include "../reader/JFJochStartMessageReader.h"
#include "BrokerFeed.h"
#include "../writer/HDF5NXmx.h"
#include <hdf5.h>
#include <spdlog/sinks/basic_file_sink.h>
#include <spdlog/sinks/dist_sink.h>
#include <spdlog/sinks/ringbuffer_sink.h>
#include <spdlog/sinks/stdout_color_sinks.h>

#include "../common/CudaJitCache.h"
#include "../common/Logger.h"
#include "../common/ThreadAffinity.h"
#include "../common/GitInfo.h"
#include "../common/time_utc.h"
#include "../common/Definitions.h"
#include "../common/DiffractionExperiment.h"
#include "../common/PixelMask.h"
#include "../common/CUDAWrapper.h"
#include "../common/JFJochMath.h"
#include "../image_analysis/bragg_integration/CalcISigma.h"
#include "../image_analysis/geom_refinement/Calibrants.h"
#include "../image_analysis/indexing/IndexerThreadPool.h"
#include "../image_analysis/LoadFCalcFromMtz.h"
#include "../image_analysis/SensorAbsorption.h"
#include "../image_analysis/UpdateReflectionResolution.h"
#include "../image_analysis/WriteReflections.h"
#include "../image_analysis/scale_merge/CrystalSetting.h"   // CellInBasis, HklOperator
#include "../image_analysis/scale_merge/Merge.h"
#include "../image_analysis/scale_merge/RfreeFlags.h"
#include "../image_analysis/scale_merge/ReindexAmbiguity.h"   // MatchReference
#include "../image_analysis/scale_merge/ScaleOnTheFly.h"
#include "../image_analysis/scale_merge/StillsPartialityRefine.h"
#include "../image_analysis/scale_merge/SublatticeRelabel.h"
#include "../image_analysis/scale_merge/RotationScaleMerge.h"
#include "../image_analysis/scale_merge/ResolutionCutoff.h"
#include "../image_analysis/scale_merge/AnisotropyAnalysis.h"
#include "../image_analysis/scale_merge/FrenchWilson.h"
#include "../image_analysis/scale_merge/TwinningAnalysis.h"
#include "../image_analysis/scale_merge/TranslationalNCS.h"
#include "../image_analysis/scale_merge/SearchSpaceGroup.h"
#include "Rugnux.h"
#include "RugnuxDefaults.h"
#include "../image_analysis/structure_refinement/ModelValidation.h"
#include "../writer/WriteModel.h"
#include "../writer/RugnuxModelFile.h"
#include "ResultReport.h"
#include "RugnuxOutputFiles.h"
#include "RugnuxConsole.h"
#ifdef __APPLE__
#include "../image_analysis/bragg_integration/BraggIntegrationEngineMetal.h"
#endif


// Default rot3d per-frame scale-G smoothing range (XDS DELPHI-like), in degrees of rotation.
constexpr double SMOOTH_G_DEFAULT_DEG = 5.0;

// Default rot3d per-batch relative-B batch width (bare --relative-b), in degrees of rotation.
constexpr double RELATIVE_B_DEFAULT_DEG = 10.0;

// What the run does (--mode). Each of these was once a flag of its own; one option keeps them
// mutually exclusive by construction.
enum class RugnuxMode { MX, Azint, Scale, Calibration };

// Azimuthal sectors used by --mode calibration --calibration rings when --azim-phi-bins was not given.
// The default of 1 is a plain radial profile, in which a ring has been averaged over every direction so
// nothing is left to say where its centre is (RingsFromAzimuthalProfile refuses below 4). Sweeping the
// count on a LaB6 exposure and on a crystal's ice rings, 32 and above agree to about 0.1 px and the
// residual is flat, while 8 sectors is visibly coarser (0.3 px away, twice the residual). Going higher
// buys nothing and runs into the 65534-bin limit on q x azimuth, so 32 is the default.
constexpr int CALIBRATION_AZIM_BINS_DEFAULT = 32;

void print_usage() {
    std::cout << "Usage rugnux {<options>} <input.h5> [<broker URL>]" << std::endl;
    std::cout << "   With a broker URL (http://host:port/) and no <input.h5> on disk yet, follows the broker's current "
                 "collection while it is written: <input.h5> must be the path its master file will have, the data "
                 "files are read next to it as the broker reports them closed, and the run ends with the images the "
                 "collection delivered. Rotation data, --mode mx only. The collection's token is read from the "
                 "environment variable JUNGFRAUJOCH_HTTP_TOKEN and sent only to the broker. With <input.h5> on disk, "
                 "the URL is ignored" << std::endl;
    std::cout << "   --simulate-live <ms>             Read the stored <input.h5> as the collection it was while being written, "
                 "the way a broker URL follows one: image i becomes readable (i+1)*<ms> ms after the run starts (0: all "
                 "at once). The run then takes the live path - the first passes decide their near ties on the images in "
                 "so far, re-checked once the last one is in, and the run is made again where one ends elsewhere - "
                 "where on a stored sweep they decide on all of its images at once. Same result; for testing the "
                 "live workflow without a broker. --mode mx only" << std::endl;
    std::cout << "   --fast-live                      With --simulate-live or a broker URL: run as the broker's rugnux live "
                 "mode does - every decision stands where it was first taken, nothing is checked or run again once the "
                 "sweep is in (near-tie re-checks, geometry and rotation-scale walks, metric-symmetry arms, supercell and "
                 "quality guards, doubled cell), the integration radius is fixed, and SIGINT cuts the run to what it has "
                 "established. A difficult crystal can come out worse" << std::endl;
    std::cout << "Options:" << std::endl;
    std::cout << "   -o, --output-prefix <txt>        Output file prefix (default: output). mx and scale runs always write "
                 "<prefix>_report.txt, the results report; every run writes <prefix>_log.txt, the full timestamped log "
                 "(debug level); an empty prefix writes nothing at all" << std::endl;
    std::cout << "   -N, --threads <num>              Number of threads (default: every CPU the run may use - its affinity and cgroup quota - of which the "
                 "per-image loop uses at most 16 per GPU; an explicit value is used as given)" << std::endl;
    std::cout << "   --no-gpu                         Run on the CPU only, as on a machine without a GPU: CUDA is not "
                 "touched and every GPU step takes its CPU path (-X Auto and FFT index with FFTW)" << std::endl;
    std::cout << "   -s, --start-image <num>          Start image number (default: 0)" << std::endl;
    std::cout << "   -e, --end-image <num>            End image number (default: all)" << std::endl;
    std::cout << "   -t, --stride <num>               Image stride (default: 1)" << std::endl;
    std::cout << "   -v, --verbose                    Show the whole log on the terminal in place of the steps "
                 "(the log file is written either way)" << std::endl;
    std::cout << std::endl;

    std::cout << "  Mode" << std::endl;
    std::cout << "   --mode <name>                    What this run does (default: mx)" << std::endl;
    std::cout << "        mx            Full analysis - spot finding, indexing, integration and merging" << std::endl;
    std::cout << "        azint         Only azimuthal integration (no spot finding/indexing); writes <prefix>_process.h5" << std::endl;
    std::cout << "        scale         Only re-scale/merge the already-integrated reflections in <input> (no re-integration)" << std::endl;
    std::cout << "        calibration   Determine the detector geometry from powder rings; writes <prefix>.poni for pyFAI and <prefix>.json, whose dataset_settings member is a jfjoch_broker dataset_settings body as it stands" << std::endl;
    std::cout << std::endl;

    std::cout << "  Calibration (--mode calibration)" << std::endl;
    std::cout << "   --calibrant <name>               Powder standard: lab6|agbh|ceo2|si|ice (default: lab6, case-insensitive). Overridden by -C: a unit cell given there IS the standard, with its rings enumerated from the cell and its absences from -S where that is given, or taken as primitive where it is not. -S supplies SYMMETRY absences only: a standard whose extinctions come from its atomic basis rather than from a symmetry element - silicon, whose 222 is absent in Fd-3m for that reason - is better named with --calibrant" << std::endl;
    std::cout << "   --calibration <txt>              How the rings are measured: rings|spots (default: rings). rings sums the (q x azimuth) azimuthal profile over every processed image and fits the ring arcs in it; spots pools the found spots and fits those. -s/-e/--stride select the images; rings defaults --azim-phi-bins to 32" << std::endl;
    std::cout << "   --no-refine-tilt                 Do not refine the detector tilt: hold rot1/rot2 at the header value and fit only the beam centre and the distance. For a calibration handed to a program that cannot express a tilted detector, e.g. XDS" << std::endl;
    std::cout << std::endl;

    std::cout << "  Detector geometry" << std::endl;
    std::cout << "   --crystfel-geometry <file>       Read <input> - an HDF5/CXI file, or a directory of them - as CrystFEL does with this geometry file: frames from its data path, panels placed at its corners, camera length, pixel size, gain, photon energy and bad regions from it. One wavelength and one camera length for the run; panel positions are taken as given" << std::endl;
    std::cout << std::endl;

    std::cout << "  Detector mask" << std::endl;
    std::cout << "   --detect-beam-stop[=N|off]       Find the beam stop and its holder in a projection of N images and add them to the pixel mask (bit 9), so nothing shadowed by them is integrated. ON by default (60 images); =off disables. Reflections behind the stop are attenuated but not flagged, so they are integrated low with a plausible sigma and no existing rejection catches them" << std::endl;
    std::cout << "   --beam-center-check[=off]        Measure the beam centre from the isotropy of the scattered background on EVERY run, report how far the file's value is from it, and index a second first pass with it to see whether the two centres give the same lattice. The fit reads the projection --detect-beam-stop already builds, so it costs no extra frames. On a run that indexes, the measured centre is adopted where the file's centre indexes nothing and the measured one indexes a majority, and where the two centres return cells related by an integer volume factor, in either direction, and the measured centre's lattice carries materially more of the pooled spots against its own chance level - the axis harmonic a centre error along the spindle produces, which nothing downstream repairs. Where the indexing cannot tell the two centres apart - the same cell with a different metric symmetry, or the same lattice found at both only by reading less of each frame - the first pass is run at both and the run keeps the one that merges better (on the same lattice: the one that measures more reflections at I/sigma >= 2). ON by default; =off disables" << std::endl;
    std::cout << std::endl;

    std::cout << "  Spot finding" << std::endl;
    std::cout << "   --spot-sigma <num>               Noise sigma level for spot finding (default: 4.0)" << std::endl;
    std::cout << "   --spot-threshold <num>           Photon count threshold for spot finding (default: 10)" << std::endl;
    std::cout << "   --min-pix-per-spot <num>         Minimum connected strong pixels per spot. If omitted, min-pix is chosen PER IMAGE (stills indexing): the frame is scored at min-pix 2/3/1 (one lattice search per frame, refined on each list) and the one maximising indexed count x indexed fraction is kept. Give an explicit value to force a fixed min-pix instead." << std::endl;
    std::cout << "   --adaptive-spots                 Self-calibrating detection (DEFAULT): the strong-pixel threshold comes from each image's own per-resolution-ring noise instead of the fixed --spot-threshold, so one setting adapts across datasets (no per-dataset --spot-threshold/--spot-sigma tuning)." << std::endl;
    std::cout << "   --no-adaptive-spots              Turn adaptive detection off and use the fixed --spot-threshold / --spot-sigma finder instead" << std::endl;
    std::cout << "   --spot-false-pixels <num>        Adaptive detection operating point: expected noise pixels tolerated per frame (default: 100; implies --adaptive-spots)" << std::endl;
    std::cout << "   --spot-high-resolution <num>     High resolution limit for spot finding. If omitted (or 0), spot finding is not clipped in resolution and extends as far as the detector reaches" << std::endl;
    std::cout << "   --spot-low-resolution <num>      Low resolution limit for spot finding, in A (default: 50; lower it, e.g. 24, to exclude the direct-beam halo on weakly-diffracting serial data; 0 removes the limit)" << std::endl;
    std::cout << "   --max-spots <num>                Max spot count per image, the strongest ones, handed to indexing. Default: measured from the data on rotation (as deep into each image's spot list as its spots still lie on the lattice), capped at 1000" << std::endl;
    std::cout << "   --detect-ice-rings[=on|off]      Flag ice-ring spots (de-prioritised in indexing) and exclude ice-ring reflections from scaling. Default: the master file's setting, or - where the file says nothing - on for rotation and off for stills" << std::endl;
    std::cout << std::endl;

    std::cout << "  Indexing" << std::endl;
    std::cout << "   (A dataset with a rotation goniometer axis is processed as rotation data by default; use --force-still to override)" << std::endl;
    std::cout << "   --force-still                    Process a rotation (goniometer) dataset as independent stills (still indexing + per-image ScaleOnTheFly) instead of rotation" << std::endl;
    std::cout << "   -R, --two-pass-rotation[=num]    Two-pass offline rotation indexing (default for goniometer data; optional first-pass image count, default: 100)" << std::endl;
    std::cout << "   --single-pass-rotation[=num]     Use online-like single-pass rotation indexing (optional: min angular range deg)" << std::endl;
    std::cout << "   --min-indexed-spots <num>        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, and integration is not gated by it" << std::endl;
    std::cout << "   --force-rotation-lattice <vec>   Force rotation indexer with external lattice (in Angstrom) : \"a0x,a0y,a0z,a1x,a1y,a1z,a2x,a2y,a2z\" (9 floats, skips first pass)" << std::endl;
    std::cout << "   --rotation-scale <k>             Goniometer rotation scale: the stage turned k times the angle stored in the file (the commanded one). Applied to both passes; overrides the fitted correction" << std::endl;
    std::cout << "   --rotation-no-postrefine         Disable the (default-on) two-pass rotation post-refine (post-refine detector distance/beam + cell/axis, then re-integrate; only the refined pass is written, as the canonical <prefix>_* output)" << std::endl;
    std::cout << "   --prepass-fraction <f>           Integrate the first fraction f of the sweep, but at least 120 deg of it, in the two-pass rotation geometry pre-pass (0.05-1, default 0.5; 1 = the whole sweep); pass 2 reads every frame. The pre-scan and the first-pass indexing sample the same part of the sweep" << std::endl;
    std::cout << "   -X, --indexing-algorithm <txt>   Indexing algorithm (Auto|FFT|cuFFT|FFTW|FFBIDX|None, default Auto). FFT is "
                 "the de-novo FFT search, on the GPU (cuFFT) where there is one and --no-gpu is not given, otherwise on the "
                 "CPU (FFTW); cuFFT and FFTW name one implementation each. cuFFT and FFBIDX (known cell) need a GPU" << std::endl;
    std::cout << "   -S, --space-group <num|symbol>   Space group number (96) or symbol (P43212) - for indexing and scaling" << std::endl;
    std::cout << "   -C, --unit-cell <cell>           Fix reference unit cell: \"a,b,c,alpha,beta,gamma\"" << std::endl;
    std::cout << "   --fft-min-unit-cell <num>        Shortest cell axis the FFT search accepts, in A (default: 10). A candidate with a shorter axis is discarded, but a de-novo rotation run also tries a second first-pass hypothesis with the floor at 5 A, so a small-molecule cell is indexed without this flag; -C lowers it on its own to cover the cell given" << std::endl;
    std::cout << "   -r, --refine <txt>               Geometry refinement algorithm (none|orientation|beam_and_lattice|flex); flex tries all three per image and keeps whichever indexes the most spots (alias: multi)" << std::endl;
    std::cout << "   --refine-geometry[=N|off]        Stills: extra first pass that bundle-adjusts the shared beam/distance/cell from N strongly-indexed frames (default: 200) then re-indexes (lifts weak-stills indexing). Default ON for stills when a reference cell is given (-C / reference MTZ); =off disables" << std::endl;
    std::cout << "   --index-ice-rings[=on|off]       Index on the spots flagged as sitting on an ice ring too, instead of setting them aside (default: off; no effect without --detect-ice-rings)" << std::endl;
    std::cout << std::endl;

    std::cout << "  Scaling and merging (on by default)" << std::endl;
    std::cout << "   --no-merge                      Skip scaling and merging; write only the per-image _process.h5" << std::endl;
    std::cout << "   --scale-fulls                   rot3d: after the 3D combine, refit a per-frame scale on the fulls (XDS order, Unity model). Default ON for rot3d" << std::endl;
    std::cout << "   --no-scale-fulls                Disable the rot3d scale-fulls refit (it is on by default for rot3d)" << std::endl;
    std::cout << "   --write-process-h5              Also write the (large) _process.h5 when merging (default: only .mtz/.cif when merging)" << std::endl;
    std::cout << "   --finalist-ledger               Report the full-resolution evidence for each space group the search considered, not only the one it adopted, and the twin-immune zone evidence of the adopted group's 2-folds (report-only; the decision is unchanged). Both are read on a merge of the observations in P1 that only this option makes, so it costs one extra merge" << std::endl;
    std::cout << "   --developer                     Write the full <prefix>_report.txt: the pipeline-internal keys (the anisotropy gate, the space-group candidate and operator tables, the model-fit null, the sweep internals) and the long explanations, which the default report leaves out. Nothing is computed differently - the same report, rendered in full" << std::endl;
    std::cout << "   --smooth-g[=deg]                rot3d: smooth per-frame scale G over a deg-degree rotation range (XDS DELPHI-like) before the combine (default: 5 for rot3d; 0 = off)" << std::endl;
    std::cout << "   --relative-b[=deg]              rot3d: fit a per-batch relative-B (beyond the single decay slope) over deg-degree batches; cross-validated (default: 10 deg when bare; off otherwise)" << std::endl;
    std::cout << "   --no-scaling-corrections        rot3d: disable the (default-on) decay + absorption + modulation correction surfaces fitted on the fulls after scale-fulls" << std::endl;
    std::cout << "   --no-expected-variance-merge    stills: disable the default expected-variance merge weighting (which rebuilds each weak observation's signal variance at the reflection mean to de-bias the inverse-variance merge); restores observed-sigma weighting" << std::endl;
    std::cout << "   -A, --anomalous                 Anomalous mode (don't merge Friedel pairs)" << std::endl;
    std::cout << "   --scaling-high-resolution <num> High resolution limit for scaling/merging (manual override; default: no limit)" << std::endl;
    std::cout << "   --scaling-low-resolution <num>  Low resolution limit for scaling/merging, in A (default: 50, also XDS's own default; 0 = no limit). The beam stop suppresses air scatter well beyond the shadow the beam-stop mask covers, so reflections coarser than this are measured on a depressed background and mostly integrate negative; masking does not reach them" << std::endl;
    std::cout << "   --resolution-cutoff <txt>       Automatic high-resolution cutoff for the written reflections + reported shells: cc-logistic|off (default: cc-logistic; ignored when --scaling-high-resolution is set)" << std::endl;
    std::cout << "   --resolution-cc-target <num>    CC1/2 target defining the cc-logistic fall-off (default: 0.30)" << std::endl;
    std::cout << "   --resolution-shells <num>       Number of resolution shells in the reported statistics table (default: 9, as XDS)" << std::endl;
    std::cout << "   --report-resolution <dmin>[,<dmax>] Also report the merging statistics over this resolution range (A, either order; dmax defaults to the run's own low-resolution limit) as a second table beside the run's own - the REFRES_* keys of the report - binned from the same merged reflections, so a run can be read against another program's table at that program's range. Report-only: the cut, the scaling, the error model and every decision stay the run's own, and shells finer than the run's own limit are empty rather than filled from data the run did not keep" << std::endl;
    std::cout << "   --ice-min-score <num>           Ice-presence gate: measured ice score (1 = no ice) a run must reach before ANY ice handling is applied - the flagging and the exclusion from scaling (default: 1.5). The eleven hexagonal bands cover 16-26% of the unique reflections whether or not the crystal has ice, so handling ice on a clean crystal is a pure loss. 0 = no gate (always handle ice)" << std::endl;
    std::cout << "   --ice-min-spot-ratio <num>      Second ice-presence channel: found spots on the hexagonal rings over the same q width of ice-free flanks beside them (1 = spots spread evenly). Ice in large crystallites diffracts as discrete spots and leaves the radial profile flat, so --ice-min-score alone is blind to it. Default 2.0; 0 disables this channel" << std::endl;
    std::cout << "   --min-partiality <num>          Minimum partiality to accept reflection (default: 0.02)" << std::endl;
    std::cout << "   --capture-uncertainty <num>     rot3d: systematic sigma ~num*(1-captured_fraction)*I on under-captured fulls (default: 1.0 for rot3d, 0 otherwise)" << std::endl;
    std::cout << "   --min-captured-fraction <num>   rot3d: drop a combined full whose rocking curve was captured below this fraction (edge-of-sweep truncated fulls) (default: 0.7 for rotation, 0 otherwise; 0 = off)" << std::endl;
    std::cout << "   --mosaicity <num>               Diagnostic: fix the scaling mosaicity (deg) instead of the per-image seed" << std::endl;
    std::cout << "   --prediction-mosaicity <num>    Diagnostic: fix the rocking width the PREDICTION window opens to (deg), leaving the partiality on the per-image sigma_M. Prediction and partiality are one number by default, so a sigma_M that moves takes the integrated reflection population with it" << std::endl;
    std::cout << "   --reject-outliers <num>         Per-observation merge outlier rejection, N sigma from the per-reflection median (default: 6 for rot3d, XDS/DIALS-style; 0 = off)" << std::endl;
    std::cout << "   --search-min-zeta <num>         De-novo space-group search only: also search a merge of just the observations whose Lorentz geometry |zeta| reaches this, and report both answers (default: 0.85 for rotation, 0 = single search). Reflections crossing the Ewald sphere near-tangentially are measured worst and can make a real symmetry operator look like a twin law; where the two searches disagree, the merge of ALL the observations decides" << std::endl;
    std::cout << "   --min-image-cc <num>            Per-image CC limit in percent (default: no limit)" << std::endl;
    std::cout << "   --scaling-iterations <num>      Cap on the per-frame scaling iterations; the loop stops earlier once the scales settle (default: 100)" << std::endl;
    std::cout << "   -z, --reference <file>          Reference data of the same crystal form: an MTZ, or a PDB structure-factor mmCIF (e.g. 1abc-sf.cif, first merged block with a usable column; R-free set from _refln.status f/o, else pdbx_r_free_flag). Gzipped or not, recognised by content. --reference-mtz is the same option" << std::endl;
    std::cout << "   --reference-column <label>      Reference column to use, by MTZ label; an mmCIF is read under the labels gemmi cif2mtz gives it (IMEAN, FP, I(+), FC, F-model, ...) (default: auto - F-model, else IMEAN/I, else FP/FOBS/F)" << std::endl;
    std::cout << "   --model <file>                  After merging, validate vs this atomic model: R-free, sigma_A-weighted 2mFo-DFc/mFo-DFc maps, the model as placed (written beside them), and - where the merge kept the Bijvoet split - an anomalous difference map with the strongest anomalous scatterers named by the atom they sit on. PDB or mmCIF, gzipped or not, recognised by content rather than by extension. A prediction (AlphaFold or ModelCIF, pLDDT in the B column), or an experimental structure the rigid body does not place against its null, is placed by molecular replacement instead (see --mr)" << std::endl;
    std::cout << "   --mr <file>                     As --model, but placed by molecular replacement straight away, without the rigid-body placement first: as many copies as the cell holds, in every space group the merge cannot tell apart and in the twin hypothesis' subgroup. A prediction is trimmed to the residues of pLDDT 70 and above, and where the AlphaFold DB's predicted-aligned-error JSON sits beside it under its own name it is cut into rigid domains; any other PDB or mmCIF is taken as an experimental structure, its polymer only (no waters, ligands, hydrogens or alternative conformers). Which of the two it is is read from the file. It may relabel the enantiomorph of the answer, and a different space group it chooses is written beside the answer as <prefix>_mr.mtz/.cif with the placed model <prefix>_mr_model.pdb. --mode mx only" << std::endl;
    std::cout << "   --export-unmerged               Write <prefix>_unmerged.mtz, an unmerged MTZ (POINTLESS column layout) of the integrated observations, for aimless / pointless / careless. On by default, whenever there is an output prefix. On a rotation run the partials of each reflection are summed into one full, written at the batch its rocking curve is centred on, with the summed rocking-curve fraction in FRACTIONCALC; an event that caught less of its rocking curve than --min-captured-fraction (or --min-partiality) is not written, exactly as in the merge, since a full is what the reading program is told these rows are. Intensities carry the deterministic per-reflection corrections and nothing else - Lorentz and polarization in the LP column, the sensor's angle-dependent efficiency in QE and the flight path's attenuation in FLIGHT, so raw counts are I / LP * QE * FLIGHT - while the partiality is not divided out and the per-image scale is not applied at all, since those programs scale the data themselves. Written in --mode mx and --mode scale, and with --no-merge" << std::endl;
    std::cout << "   --no-export-unmerged            Do not write <prefix>_unmerged.mtz. It is the largest file a run produces, so a run whose observations are not going to another scaling program - a regression battery, say - can skip writing it" << std::endl;
    std::cout << "   --export-unmerged-partials      Write <prefix>_unmerged_partials.mtz, the same observations with each partial as its own row (one batch per image) flagged for the reading program to sum, instead of summed here. Off by default and independent of --export-unmerged; both can be written in one run" << std::endl;
    std::cout << std::endl;

    std::cout << "  Integration" << std::endl;
    std::cout << "   --bandwidth <num>               Relative X-ray bandwidth FWHM (e.g. 0.01 for 1% DMM). Default: the file's value, else measured in the pre-scan from the radial elongation of strong spots and used where significant, else 0; --bandwidth 0 forces a monochromatic beam" << std::endl;
    std::cout << "   --integration-radius <r>        Signal-box radius r1, or r1,r2,r3 (px). One value => r2=r1+2, r3=r1+4" << std::endl;
    std::cout << "   --adaptive-integration-radius[=on|off] Set the signal radius r1 from how wide this crystal's spots actually are, measured in the pre-scan (default: on for rotation, off for stills). r1 is the aperture the integrator learns the profile WIDTH over, and a second moment over a disk of radius a saturates at a^2/4, so at the shipped r1=4 the learned sigma can never exceed 2 px and a broader spot is fitted with a profile the model cannot represent. r80 - the radius holding 80% of a spot's flux, at a common resolution - is read off isolated strong spots over a fixed aperture that owes nothing to r1, and r1 = clamp(round(2*r80), 4, 6); the background ring keeps the area it has at the default 4,6,13. Ignored when --integration-radius is given" << std::endl;
    std::cout << "   --integration-stencil <k>       Push the r2..r3 background ring out by k times the beam's radial streak (bandwidth*Rpx), per reflection (default 0 = a fixed circular ring). A fixed ring otherwise ends up on a streaked reflection's own tails at high resolution and measures them as background. Only the ring moves, and only radially - the r1 signal box stays a circle. On a monochromatic beam the streak is zero and this does nothing" << std::endl;
    std::cout << "   --integration-high-resolution <num> High resolution limit for prediction/integration. If omitted (or 0), integration extends as far as the detector reaches" << std::endl;
    std::cout << "   --max-hkl <n>                   Predict reflections with |h|,|k|,|l| <= n. Default: derived per crystal from the refined cell (ceil(longest axis / d_min) + 1), which is the exact bound - set it only to override that" << std::endl;
    std::cout << "   --background-clip <n>           High-side clip of the background ring at mean + n*sqrt(mean) (default 4; 0 = off). This is the default background estimator - it rejects neighbour cores and zingers without the symmetric trim's Poisson skew bias. Ignored by --integrator boxsum" << std::endl;
    std::cout << "   --background-radial[=on|off|auto] Correct the background ring for the CURVATURE of the radial background (default auto). The signal disk and the background ring are concentric, so a background linear in position cancels between them and only curvature survives - which on a smooth ice ring reaches +26 counts on a single reflection. =auto applies it per image where that image's ice score shows a smooth powder ring, which is where a radius-only background model holds; on ice made of discrete crystallite spots there is no such ring and the correction makes the bias worse. Costs one short dot product per reflection and no extra pixel reads" << std::endl;
    std::cout << "   --background-trim <f>           Use the old symmetric trimmed mean for the background ring instead of the clip (0<=f<0.5; 0.10 was the former default). Switches --background-clip off. A symmetric trim is biased low on Poisson data and adds ~5 counts to every partial, so this is for back compatibility only; 0 = plain ring mean" << std::endl;
    std::cout << "   --overlap <txt>                 What to do where two predicted reflections share signal pixels: off|reject|exclude (default exclude). A pixel inside two signal disks belongs to the nearer centre; before this, nothing kept a neighbour's flux out of a reflection's own disk, so on a dense pattern a crowded reflection read high. exclude drops the shared PIXELS from the profile fit, which renormalises itself, so the reflection is kept; reject instead drops the whole reflection when less than --overlap-minpk of its expected profile is cleanly its own (what XDS calls MINPK). --integrator boxsum has no profile to renormalise with, so exclude does nothing there and only reject acts" << std::endl;
    std::cout << "   --overlap-minpk <f>             Least fraction of a reflection's expected profile that must be usable for the reflection to be kept (default 0.75, XDS MINPK). Governs both ways part of a profile is lost: the fraction that must be READABLE - not masked, untrusted, in a detector gap or overloaded - in every profile mode, and, under --overlap reject, the fraction that must be cleanly the reflection's own. --integrator boxsum has no profile to renormalise with, so there a signal disk with any unreadable pixel is still discarded outright and the reject fraction is by disk AREA, which cuts harder" << std::endl;
    std::cout << "   --integrator <txt>              Spot integrator boxsum|gaussian|empirical (default: gaussian profile-fit; boxsum is the classical fallback)" << std::endl;
    std::cout << "   --simple-stills                 stills: treat every reflection as a full (p=1, single-pass scale/merge); disables the default physical partiality post-refinement" << std::endl;
    std::cout << "   -q, --azim-q-spacing <num>      Azimuthal-integration Q bin spacing (1/A) (default: 0.01)" << std::endl;
    std::cout << "   --azim-min-q <num>              Azimuthal-integration minimum Q (1/A)" << std::endl;
    std::cout << "   --azim-max-q <num>              Azimuthal-integration maximum Q (1/A). If omitted, integration extends to the highest Q the detector reaches." << std::endl;
    std::cout << "   --azim-phi-bins <num>           Number of azimuthal (phi) bins (default: 1)" << std::endl;
    std::cout << "   --polarization-correction <on|off>  Enable/disable azimuthal polarization correction" << std::endl;
    std::cout << "   --solid-angle-correction <on|off>   Enable/disable azimuthal solid angle correction" << std::endl;
    std::cout << "   --flight-path <txt>             What the diffracted beam crosses between the sample and the detector: air|helium|vacuum (default air). A reflection arriving at angle alpha to the detector normal flies D/cos(alpha) instead of D, so it crosses more of the medium and reads low; the factor is exp(D/L*(1/cos(alpha)-1)) from the NIST attenuation coefficient of the medium, the stated distance and the stated wavelength, and nothing in it is fitted. NOTHING IN ANY FILE STATES THE MEDIUM - no field of the NXmx application definition, and none of any master rugnux reads - so it cannot be detected and is assumed. Nor can it be inferred from the implied transmission: in this corpus a confirmed helium station sits at 51% implied air transmission and a confirmed air station at 63%. Air costs +1.5% at alpha = 55 deg for 18 keV over 160 mm and several-fold below 5 keV, where stations use helium precisely because air is unusable; helium attenuates about 1/600 of air, and vacuum leaves intensities untouched. The assumption and what it is worth are printed in the report" << std::endl;
    std::cout << std::endl;

    std::cout << "  Geometry overrides (defaults taken from the input file)" << std::endl;
    std::cout << "   --beam-x <num>                   Beam center X (pixel)" << std::endl;
    std::cout << "   --beam-y <num>                   Beam center Y (pixel)" << std::endl;
    std::cout << "   --detector-distance <num>        Detector distance (mm)" << std::endl;
    std::cout << "   --wavelength <num>               Wavelength (A)" << std::endl;
    std::cout << "   --rot1 <num>                     PONI rotation 1 (rad)" << std::endl;
    std::cout << "   --rot2 <num>                     PONI rotation 2 (rad)" << std::endl;
    std::cout << "   --rot3 <num>                     PONI rotation 3, about the beam (rad)" << std::endl;
    std::cout << "   --detector-mirror-y              Stored image is mirrored in Y vs the detector" << std::endl;
    std::cout << "   --detector-quarter-turns <0-3>   Stored image is turned by this many 90 deg about the beam" << std::endl;
    std::cout << "   --polarization <num>             Degree of polarization p (XDS FRACTION_OF_POLARIZATION = (1+p)/2), signed: positive for a horizontally polarized source, negative for a vertically polarized one (the sign rotates the polarization plane by 90 degrees). Default: what a miniCBF \"# Polarization\" line or a d*TREK SOURCE_POLARZ states (a fraction f, read as p = 2f - 1, so 0.5 from a laboratory tube is unpolarized), and otherwise 0.99, an undulator value; bending-magnet and wiggler sources are typically lower (0.8-0.95), and neither ADSC SMV, marCCD nor NXmx files state it, so pass a known beamline value here" << std::endl;
    }

enum {
    OPT_SPOT_SIGMA = 1000,
    OPT_SPOT_THRESHOLD,
    OPT_MIN_PIX_PER_SPOT,
    OPT_ADAPTIVE_SPOTS,
    OPT_NO_ADAPTIVE_SPOTS,
    OPT_SPOT_FALSE_PIXELS,
    OPT_SPOT_RESOLUTION,
    OPT_SPOT_LOW_RESOLUTION,
    OPT_MAX_SPOTS,
    OPT_MIN_PARTIALITY,
    OPT_MIN_IMAGE_CC,
    OPT_SEARCH_MIN_ZETA,
    OPT_SCALING_ITERATIONS,
    OPT_SCALING_HIGH_RESOLUTION,
    OPT_SCALING_LOW_RESOLUTION,
    OPT_RESOLUTION_CUTOFF,
    OPT_RESOLUTION_CC_TARGET,
    OPT_RESOLUTION_SHELLS,
    OPT_REPORT_RESOLUTION,
    OPT_SINGLE_PASS_ROTATION,
    OPT_FORCE_ROTATION_LATTICE,
    OPT_MIN_INDEXED_SPOTS,
    OPT_ROTATION_NO_POSTREFINE,
    OPT_PREPASS_FRACTION,
    OPT_ROTATION_SCALE,
    OPT_BACKGROUND_CLIP,
    OPT_BACKGROUND_RADIAL,
    OPT_REFINE_GEOMETRY,
    OPT_DETECT_BEAM_STOP,
    OPT_BEAM_CENTER_CHECK,
    OPT_BANDWIDTH,
    OPT_INTEGRATION_RADIUS,
    OPT_ADAPTIVE_INTEGRATION_RADIUS,
    OPT_INTEGRATION_STENCIL,
    OPT_BACKGROUND_TRIM,
    OPT_OVERLAP,
    OPT_OVERLAP_MINPK,
    OPT_MAX_HKL,
    OPT_INTEGRATION_HIGH_RES,
    OPT_REJECT_OUTLIERS,
    OPT_REFERENCE_COLUMN,
    OPT_MODEL,
    OPT_CRYSTFEL_GEOMETRY,
    OPT_MR,
    OPT_EXPORT_UNMERGED,
    OPT_NO_EXPORT_UNMERGED,
    OPT_EXPORT_UNMERGED_PARTIALS,
    OPT_DUMP_OBSERVATIONS,
    OPT_INTEGRATOR,
    OPT_SIMPLE_STILLS,
    OPT_SCALE_FULLS,
    OPT_CAPTURE_UNCERTAINTY,
    OPT_MIN_CAPTURED_FRACTION,
    OPT_MOSAICITY,
    OPT_PREDICTION_MOSAICITY,
    OPT_SMOOTH_G,
    OPT_RELATIVE_B,
    OPT_NO_SCALING_CORRECTIONS,
    OPT_NO_EXPECTED_VARIANCE_MERGE,
    OPT_DETECT_ICE_RINGS,
    OPT_INDEX_ICE_RINGS,
    OPT_ICE_MIN_SCORE,
    OPT_ICE_MIN_SPOT_RATIO,
    OPT_NO_SCALE_FULLS,
    OPT_WRITE_PROCESS_H5,
    OPT_FINALIST_LEDGER,
    OPT_SIMULATE_LIVE,
    OPT_FAST_LIVE,
    OPT_DEVELOPER,
    OPT_NO_GPU,
    OPT_FORCE_STILL,
    OPT_AZIM_MIN_Q,
    OPT_AZIM_MAX_Q,
    OPT_AZIM_PHI_BINS,
    OPT_MODE,
    OPT_CALIBRANT,
    OPT_CALIBRATION,
    OPT_NO_MERGE,
    OPT_POLARIZATION_CORRECTION,
    OPT_SOLID_ANGLE_CORRECTION,
    OPT_FLIGHT_PATH,
    OPT_BEAM_X,
    OPT_BEAM_Y,
    OPT_DETECTOR_DISTANCE,
    OPT_WAVELENGTH,
    OPT_ROT1,
    OPT_ROT2,
    OPT_ROT3,
    OPT_DETECTOR_MIRROR_Y,
    OPT_DETECTOR_QUARTER_TURNS,
    OPT_FFT_MIN_UNIT_CELL,
    OPT_POLARIZATION,
    OPT_NO_REFINE_TILT
};

static option long_options[] = {
    {"verbose", no_argument, nullptr, 'v'},
    {"output-prefix", required_argument, nullptr, 'o'},
    {"threads", required_argument, nullptr, 'N'},
    {"start-image", required_argument, nullptr, 's'},
    {"end-image", required_argument, nullptr, 'e'},
    {"stride", required_argument, nullptr, 't'},
    {"indexing-algorithm", required_argument, nullptr, 'X'},
    {"unit-cell", required_argument, nullptr, 'C'},
    {"min-indexed-spots", required_argument, nullptr, OPT_MIN_INDEXED_SPOTS},
    {"reference", required_argument, nullptr, 'z'},
    {"reference-mtz", required_argument, nullptr, 'z'},
    {"reference-column", required_argument, nullptr, OPT_REFERENCE_COLUMN},
    {"model", required_argument, nullptr, OPT_MODEL},
    {"crystfel-geometry", required_argument, nullptr, OPT_CRYSTFEL_GEOMETRY},
    {"mr", required_argument, nullptr, OPT_MR},
    {"export-unmerged", no_argument, nullptr, OPT_EXPORT_UNMERGED},
    {"no-export-unmerged", no_argument, nullptr, OPT_NO_EXPORT_UNMERGED},
    {"export-unmerged-partials", no_argument, nullptr, OPT_EXPORT_UNMERGED_PARTIALS},
    {"dump-observations", required_argument, nullptr, OPT_DUMP_OBSERVATIONS},
    {"space-group", required_argument, nullptr, 'S'},
    {"anomalous", no_argument, nullptr, 'A'},
    {"mode", required_argument, nullptr, OPT_MODE},
    {"calibrant", required_argument, nullptr, OPT_CALIBRANT},
    {"calibration", required_argument, nullptr, OPT_CALIBRATION},
    {"no-refine-tilt", no_argument, nullptr, OPT_NO_REFINE_TILT},
    {"no-merge", no_argument, nullptr, OPT_NO_MERGE},
    {"scale-fulls", no_argument, nullptr, OPT_SCALE_FULLS},
    {"no-scale-fulls", no_argument, nullptr, OPT_NO_SCALE_FULLS},
    {"write-process-h5", no_argument, nullptr, OPT_WRITE_PROCESS_H5},
    {"finalist-ledger", no_argument, nullptr, OPT_FINALIST_LEDGER},
    {"simulate-live", required_argument, nullptr, OPT_SIMULATE_LIVE},
    {"fast-live", no_argument, nullptr, OPT_FAST_LIVE},   // the broker's live run (ProcessConfig::fast_live)
    {"developer", no_argument, nullptr, OPT_DEVELOPER},
    {"no-gpu", no_argument, nullptr, OPT_NO_GPU},
    {"smooth-g", optional_argument, nullptr, OPT_SMOOTH_G},
    {"relative-b", optional_argument, nullptr, OPT_RELATIVE_B},
    {"no-scaling-corrections", no_argument, nullptr, OPT_NO_SCALING_CORRECTIONS},
    {"no-expected-variance-merge", no_argument, nullptr, OPT_NO_EXPECTED_VARIANCE_MERGE},
    {"refine", required_argument, nullptr, 'r'},

    {"two-pass-rotation", optional_argument, nullptr, 'R'},
    {"single-pass-rotation", optional_argument, nullptr, OPT_SINGLE_PASS_ROTATION},
    {"force-still", no_argument, nullptr, OPT_FORCE_STILL},
    {"azim-q-spacing", required_argument, nullptr, 'q'},
    {"azim-min-q", required_argument, nullptr, OPT_AZIM_MIN_Q},
    {"azim-max-q", required_argument, nullptr, OPT_AZIM_MAX_Q},
    {"azim-phi-bins", required_argument, nullptr, OPT_AZIM_PHI_BINS},
    {"polarization-correction", required_argument, nullptr, OPT_POLARIZATION_CORRECTION},
    {"solid-angle-correction", required_argument, nullptr, OPT_SOLID_ANGLE_CORRECTION},
    {"flight-path", required_argument, nullptr, OPT_FLIGHT_PATH},
    {"beam-x", required_argument, nullptr, OPT_BEAM_X},
    {"beam-y", required_argument, nullptr, OPT_BEAM_Y},
    {"detector-distance", required_argument, nullptr, OPT_DETECTOR_DISTANCE},
    {"wavelength", required_argument, nullptr, OPT_WAVELENGTH},
    {"rot1", required_argument, nullptr, OPT_ROT1},
    {"rot2", required_argument, nullptr, OPT_ROT2},
    {"rot3", required_argument, nullptr, OPT_ROT3},
    {"detector-mirror-y", no_argument, nullptr, OPT_DETECTOR_MIRROR_Y},
    {"detector-quarter-turns", required_argument, nullptr, OPT_DETECTOR_QUARTER_TURNS},
    {"fft-min-unit-cell", required_argument, nullptr, OPT_FFT_MIN_UNIT_CELL},
    {"polarization", required_argument, nullptr, OPT_POLARIZATION},
    {"force-rotation-lattice", required_argument, nullptr, OPT_FORCE_ROTATION_LATTICE},
    {"rotation-no-postrefine", no_argument, nullptr, OPT_ROTATION_NO_POSTREFINE},
    {"prepass-fraction", required_argument, nullptr, OPT_PREPASS_FRACTION},
    {"rotation-scale", required_argument, nullptr, OPT_ROTATION_SCALE},
    {"refine-geometry", optional_argument, nullptr, OPT_REFINE_GEOMETRY},
    {"detect-beam-stop", optional_argument, nullptr, OPT_DETECT_BEAM_STOP},
    {"beam-center-check", optional_argument, nullptr, OPT_BEAM_CENTER_CHECK},


    {"spot-sigma", required_argument, nullptr, OPT_SPOT_SIGMA},
    {"spot-threshold", required_argument, nullptr, OPT_SPOT_THRESHOLD},
    {"min-pix-per-spot", required_argument, nullptr, OPT_MIN_PIX_PER_SPOT},
    {"adaptive-spots", no_argument, nullptr, OPT_ADAPTIVE_SPOTS},
    {"no-adaptive-spots", no_argument, nullptr, OPT_NO_ADAPTIVE_SPOTS},
    {"spot-false-pixels", required_argument, nullptr, OPT_SPOT_FALSE_PIXELS},
    {"spot-high-resolution", required_argument, nullptr, OPT_SPOT_RESOLUTION},
    {"spot-low-resolution", required_argument, nullptr, OPT_SPOT_LOW_RESOLUTION},
    {"max-spots", required_argument, nullptr, OPT_MAX_SPOTS},
    {"min-partiality", required_argument, nullptr, OPT_MIN_PARTIALITY},
    {"capture-uncertainty", required_argument, nullptr, OPT_CAPTURE_UNCERTAINTY},
    {"min-captured-fraction", required_argument, nullptr, OPT_MIN_CAPTURED_FRACTION},
    {"mosaicity", required_argument, nullptr, OPT_MOSAICITY},
    {"prediction-mosaicity", required_argument, nullptr, OPT_PREDICTION_MOSAICITY},
    {"min-image-cc", required_argument, nullptr, OPT_MIN_IMAGE_CC},
    {"search-min-zeta", required_argument, nullptr, OPT_SEARCH_MIN_ZETA},
    {"scaling-iterations", required_argument, nullptr, OPT_SCALING_ITERATIONS},
    {"scaling-high-resolution", required_argument, nullptr, OPT_SCALING_HIGH_RESOLUTION},
    {"scaling-low-resolution", required_argument, nullptr, OPT_SCALING_LOW_RESOLUTION},
    {"background-clip", required_argument, nullptr, OPT_BACKGROUND_CLIP},
    {"background-radial", optional_argument, nullptr, OPT_BACKGROUND_RADIAL},
    {"resolution-cutoff", required_argument, nullptr, OPT_RESOLUTION_CUTOFF},
    {"resolution-cc-target", required_argument, nullptr, OPT_RESOLUTION_CC_TARGET},
    {"resolution-shells", required_argument, nullptr, OPT_RESOLUTION_SHELLS},
    {"report-resolution", required_argument, nullptr, OPT_REPORT_RESOLUTION},
    {"bandwidth", required_argument, nullptr, OPT_BANDWIDTH},
    {"integration-radius", required_argument, nullptr, OPT_INTEGRATION_RADIUS},
    {"adaptive-integration-radius", optional_argument, nullptr, OPT_ADAPTIVE_INTEGRATION_RADIUS},
    {"integration-stencil", required_argument, nullptr, OPT_INTEGRATION_STENCIL},
    {"background-trim", required_argument, nullptr, OPT_BACKGROUND_TRIM},
    {"overlap", required_argument, nullptr, OPT_OVERLAP},
    {"overlap-minpk", required_argument, nullptr, OPT_OVERLAP_MINPK},
    {"max-hkl", required_argument, nullptr, OPT_MAX_HKL},
    {"integration-high-resolution", required_argument, nullptr, OPT_INTEGRATION_HIGH_RES},
    {"integrator", required_argument, nullptr, OPT_INTEGRATOR},
    {"simple-stills", no_argument, nullptr, OPT_SIMPLE_STILLS},
    {"detect-ice-rings", optional_argument, nullptr, OPT_DETECT_ICE_RINGS},
    {"index-ice-rings", optional_argument, nullptr, OPT_INDEX_ICE_RINGS},
    {"ice-min-score", required_argument, nullptr, OPT_ICE_MIN_SCORE},
    {"ice-min-spot-ratio", required_argument, nullptr, OPT_ICE_MIN_SPOT_RATIO},
    {"reject-outliers", required_argument, nullptr, OPT_REJECT_OUTLIERS},
    {nullptr, 0, nullptr, 0}
};

void trim_in_place(std::string &t) {
    size_t b = 0;
    while (b < t.size() && std::isspace(static_cast<unsigned char>(t[b]))) b++;
    size_t e = t.size();
    while (e > b && std::isspace(static_cast<unsigned char>(t[e - 1]))) e--;
    t = t.substr(b, e - b);
};

bool parse_float_strict(const std::string &t, float &out) {
    try {
        size_t idx = 0;
        out = std::stof(t, &idx);
        return idx == t.size();
    } catch (...) {
        return false;
    }
};

// Parse a required numeric option argument, optionally bounded to [min_value, max_value], or print a
// clear error and exit. getopt hands option arguments over as raw C strings; atoi()/atof() silently
// return 0 on non-numeric input (so a typo like "--min-pix-per-spot 2O" becomes 2 or 0) and std::sto*
// throws, which would terminate the program. This rejects non-numeric input, trailing garbage
// ("1.5foo"), integer overflow, and out-of-range values. T may be integral or floating-point; the
// bounds default to the full representable range (i.e. unbounded).
template <typename T>
T parse_number_arg(const char *arg, const char *option_name, Logger &logger,
                   T min_value = std::numeric_limits<T>::lowest(),
                   T max_value = std::numeric_limits<T>::max()) {
    std::string s = arg ? arg : "";
    trim_in_place(s);
    T value{};
    bool parsed = false;
    if (!s.empty()) {
        try {
            size_t idx = 0;
            if constexpr (std::is_integral_v<T>) {
                const long long v = std::stoll(s, &idx);
                value = static_cast<T>(v);
                parsed = (idx == s.size()) && (static_cast<long long>(value) == v);  // no overflow
            } else {
                value = static_cast<T>(std::stod(s, &idx));
                parsed = (idx == s.size());
            }
        } catch (...) {}
    }
    if (!parsed) {
        logger.Error("Invalid numeric value for {}: '{}'", option_name, arg ? arg : "<null>");
        print_usage();
        exit(EXIT_FAILURE);
    }
    if (value < min_value || value > max_value) {
        logger.Error("Value for {} out of range: {} (expected {} to {})",
                     option_name, value, min_value, max_value);
        print_usage();
        exit(EXIT_FAILURE);
    }
    return value;
}

// Thin unbounded wrappers for the existing floating-point call sites.
double parse_double_arg(const char *arg, const char *option_name, Logger &logger) {
    return parse_number_arg<double>(arg, option_name, logger);
}

float parse_float_arg(const char *arg, const char *option_name, Logger &logger) {
    return parse_number_arg<float>(arg, option_name, logger);
}

// --report-resolution <d_min>[,<d_max>], in A and in either order; d_max defaults to the run's own
// low-resolution limit. Report-only - see ScalingSettings::ReportResolutionRange_A.
ReportResolutionRange ParseReportResolution(const std::string &arg, const ScalingSettings &scaling,
                                            Logger &logger) {
    std::vector<double> v;
    std::stringstream ss(arg);
    std::string tok;
    while (std::getline(ss, tok, ',')) {
        trim_in_place(tok);
        if (!tok.empty())
            v.push_back(parse_number_arg<double>(tok.c_str(), "--report-resolution", logger, 0.1, 100000.0));
    }
    if (v.empty() || v.size() > 2 || (v.size() == 2 && v[0] == v[1])) {
        logger.Error("--report-resolution expects d_min or d_min,d_max in A: '{}'", arg);
        print_usage();
        exit(EXIT_FAILURE);
    }
    ReportResolutionRange r;
    r.d_min = v.size() == 2 ? std::min(v[0], v[1]) : v[0];
    r.d_max = v.size() == 2 ? std::max(v[0], v[1])
              : scaling.GetLowResolutionLimit_A().value_or(std::numeric_limits<double>::infinity());
    return r;
}

bool parse_on_off(const char *arg, bool &out) {
    std::string s = arg ? arg : "";
    std::transform(s.begin(), s.end(), s.begin(),
                   [](unsigned char c) { return static_cast<char>(std::tolower(c)); });
    if (s == "on" || s == "1" || s == "true" || s == "yes") {
        out = true;
        return true;
    }
    if (s == "off" || s == "0" || s == "false" || s == "no") {
        out = false;
        return true;
    }
    return false;
}

std::optional<UnitCell> parse_unit_cell_arg(const char *arg) {
    if (!arg)
        return std::nullopt;

    std::string s(arg);


    trim_in_place(s);

    if (s.size() >= 2 && ((s.front() == '"' && s.back() == '"') || (s.front() == '\'' && s.back() == '\''))) {
        s = s.substr(1, s.size() - 2);
        trim_in_place(s);
    }

    std::vector<std::string> parts;
    parts.reserve(6);
    size_t start = 0;
    while (true) {
        size_t pos = s.find(',', start);
        if (pos == std::string::npos) {
            parts.push_back(s.substr(start));
            break;
        }
        parts.push_back(s.substr(start, pos - start));
        start = pos + 1;
    }

    if (parts.size() != 6)
        return std::nullopt;



    UnitCell uc{};
    if (!parse_float_strict(parts[0], uc.a)) return std::nullopt;
    if (!parse_float_strict(parts[1], uc.b)) return std::nullopt;
    if (!parse_float_strict(parts[2], uc.c)) return std::nullopt;
    if (!parse_float_strict(parts[3], uc.alpha)) return std::nullopt;
    if (!parse_float_strict(parts[4], uc.beta)) return std::nullopt;
    if (!parse_float_strict(parts[5], uc.gamma)) return std::nullopt;

    return uc;
}

std::optional<CrystalLattice> parse_lattice_arg(const char *arg) {
    if (!arg)
        return std::nullopt;

    std::string s(arg);
    trim_in_place(s);

    if (s.size() >= 2 && ((s.front() == '"' && s.back() == '"') || (s.front() == '\'' && s.back() == '\''))) {
        s = s.substr(1, s.size() - 2);
        trim_in_place(s);
    }

    std::vector<std::string> parts;
    parts.reserve(9);
    size_t start = 0;
    while (true) {
        size_t pos = s.find(',', start);
        if (pos == std::string::npos) {
            parts.push_back(s.substr(start));
            break;
        }
        parts.push_back(s.substr(start, pos - start));
        start = pos + 1;
    }

    if (parts.size() != 9)
        return std::nullopt;

    std::vector<float> vals(9);
    for (int i = 0; i < 9; i++) {
        if (!parse_float_strict(parts[i], vals[i]))
            return std::nullopt;
    }

    return CrystalLattice(vals);
}

// Shared offline-output settings for the _process.h5 / reflection writer, used by both the --scale
// path and the full-analysis path (each then sets its own space group and images-per-trigger).
void configure_offline_output(DiffractionExperiment &experiment, const std::string &output_prefix) {
    ApplyRugnuxExperimentDefaults(experiment);   // analysis policy shared with the viewer
    experiment.BitDepthImage(32).Compression(CompressionAlgorithm::BSHUF_LZ4);
    // Offline CLI: the operator chose the output path, so allow an absolute -o (the multi-user guard
    // that FilePrefix() applies is only for remotely-supplied prefixes in the broker/writer).
    experiment.FilePrefixTrusted(output_prefix);
    experiment.Mode(DetectorMode::Standard);   // full image analysis
    experiment.PixelSigned(true);
    experiment.OverwriteExistingFiles(true);
    experiment.SetFileWriterFormat(FileWriterFormat::NXmxLegacy);
    experiment.NumTriggers(1);
}

namespace {
    std::atomic<Rugnux *> g_active_process{nullptr};

    // --simulate-live: a stored sweep read as the collection it was while being written - image i is
    // read no earlier than (i + 1) frame times after the run began.
    std::chrono::microseconds simulated_frame_time{0};
    std::chrono::steady_clock::time_point simulated_start;

    template <class Reader>
    class SimulatedLive : public Reader {
    public:
        bool ReadRawImage(int64_t image_number, JFJochReaderRawImage &image) override {
            std::this_thread::sleep_until(simulated_start + simulated_frame_time * (image_number + 1));
            return Reader::ReadRawImage(image_number, image);
        }
    };

    // The terminal (see RugnuxConsole). Made first thing in RunRugnux; main uses it too, to close the
    // run on an error that escapes it.
    std::shared_ptr<RugnuxConsole> console;

    // Who made this, under what terms, and on whose shoulders - the GPL notice an interactive program
    // owes its user, and the credits the report repeats at its head - in a few lines. The version line
    // keeps the "Version X (git abcdef" form the battery reads off a bare invocation.
    void PrintBanner(RugnuxConsole &c) {
        c.Rule('=');
        c.Line(fmt::format(" rugnux  Version {}{}", jfjoch_version(),
                           jfjoch_git_sha1().empty() ? std::string()
                           : fmt::format(" (git {} {})", jfjoch_git_sha1().substr(0, 6), jfjoch_git_date())));
        c.Line(" Built with " + jfjoch_build_info(true));
        c.Line(" Copyright (C) 2019-2026 Paul Scherrer Institute. Free software under GPLv3,");
        c.Line(" with ABSOLUTELY NO WARRANTY. The methods and software rugnux builds on are");
        c.Line(" credited in ACKNOWLEDGEMENT.md, LICENSE and THIRD_PARTY_NOTICES.md.");
        c.Rule('=');
    }

    std::string g_log_file;   // <prefix>_log.txt once it is open, empty while it is not

    // The files of this run: named after the prefix and written since the run started.
    std::vector<std::string> WrittenFiles(const std::string &prefix, std::filesystem::file_time_type since) {
        namespace fs = std::filesystem;
        std::vector<std::string> out;
        if (prefix.empty())
            return out;
        const fs::path p(prefix);
        const fs::path dir = p.parent_path().empty() ? fs::path(".") : p.parent_path();
        const std::string base = p.filename().string();
        std::error_code ec;
        for (const auto &e : fs::directory_iterator(dir, ec)) {
            const std::string name = e.path().filename().string();
            // <prefix>_<anything>, or <prefix> with one of the extensions rugnux writes - not any file
            // that starts with the prefix, which would catch "p.txt" a user sent the terminal to.
            const std::string rest = name.size() > base.size() && name.compare(0, base.size(), base) == 0
                                     ? name.substr(base.size()) : std::string();
            if (rest.empty() || (rest[0] != '_' && rest != ".mtz" && rest != ".cif" && rest != ".hkl"
                                 && rest != ".poni" && rest != ".json"))
                continue;
            std::error_code ec2;
            if (e.is_regular_file(ec2) && e.last_write_time(ec2) >= since)
                out.push_back(name);
        }
        std::sort(out.begin(), out.end());
        return out;
    }

    // The last lines of every run: the files written, the time it took, and what to send with a question.
    void PrintClosing(RugnuxConsole &c, const std::string &prefix, std::filesystem::file_time_type since,
                      double wall_s) {
        const auto written = WrittenFiles(prefix, since);
        std::string files;
        for (const auto &f : written)
            files += (files.empty() ? "" : "  ") + f;
        if (!files.empty())
            c.Field("Files", files);
        c.Field("Wall time", fmt::format("{:.2f} s", wall_s));
        c.Rule('=');
        const std::string report_name = std::filesystem::path(prefix + "_report.txt").filename().string();
        const bool has_report = std::find(written.begin(), written.end(), report_name) != written.end();
        const std::string report = prefix + "_report.txt";
        if (has_report || !g_log_file.empty())
            c.Line(fmt::format(" With any question about this run, send {}.",
                               has_report && !g_log_file.empty() ? report + " and " + g_log_file
                               : has_report ? report : g_log_file));
    }

    // The end of an MX run: the verdict and the report's own one-line facts, then the closing lines.
    void PrintSummary(RugnuxConsole &c, const ReportDocument &doc, const std::string &prefix,
                      std::filesystem::file_time_type since, double wall_s) {
        c.Rule('=');
        if (!doc.verdict.empty())
            c.Field("Result", doc.verdict + ": " + doc.verdict_text);
        for (const auto &[label, value] : doc.summary_rows)
            if (label == "Space group" || label == "Unit cell" || label == "Resolution"
                || label == "Completeness" || label == "Signal" || label == "Anomalous")
                c.Field(label, value);
        PrintClosing(c, prefix, since, wall_s);
    }

    // A run that ends on an error, from wherever it exits: the step it was in is closed as failed.
    void CloseConsoleOnExit() {
        if (!console || !console->StepOpen())
            return;
        console->Fail();
        console->Rule('=');
        console->Line(fmt::format(" Stopped on an error after {:.2f} s.{}", console->Elapsed(),
                                  g_log_file.empty() ? std::string()
                                  : " With any question about this run, send " + g_log_file + "."));
    }
    void handle_sigint(int) {
        if (auto *p = g_active_process.load())
            p->Cancel();
    }

    // argv as one line, echoed at the top of the run and recorded in the results report. An argument
    // that would not survive being pasted back into a shell is single-quoted, so a file prefix with a
    // space in it comes back as the one argument it was.
    std::string JoinCommandLine(int argc, char **argv) {
        std::string out;
        for (int i = 0; i < argc; i++) {
            if (i > 0)
                out += ' ';
            const std::string arg = argv[i];
            if (arg.find_first_of(" \t\n'\"\\$`*?()[]{}<>|&;#~") == std::string::npos) {
                out += arg;
                continue;
            }
            out += '\'';
            for (char c : arg) {
                if (c == '\'')
                    out += "'\\''";
                else
                    out += c;
            }
            out += '\'';
        }
        return out;
    }

    // The input as found on disk, for the reflection files to name: its absolute path, and its size and
    // modification time - an identifier that tells two files of one name apart without reading the
    // data, which can run to terabytes. For an HDF5 data set it is the master file's. Nothing is
    // recorded about an input that is not a file here (a collection followed from the broker).
    void DescribeInput(const std::string &input_file, OutputProvenance &out) {
        std::error_code ec;
        const std::filesystem::path path = std::filesystem::absolute(input_file, ec);
        if (ec || !std::filesystem::exists(path, ec))
            return;
        out.input_file = path.lexically_normal().string();
        const auto size = std::filesystem::is_regular_file(path, ec) ? std::filesystem::file_size(path, ec)
                                                                      : std::uintmax_t{0};
        const auto modified = std::filesystem::last_write_time(path, ec);
        if (ec)
            return;
        // file_clock to system_clock through "now" on both, to the second.
        const auto sys = std::chrono::floor<std::chrono::seconds>(
                modified - std::filesystem::file_time_type::clock::now() + std::chrono::system_clock::now());
        out.input_identity = (size > 0 ? fmt::format("{} bytes, ", size) : std::string())
                             + "modified " + time_UTC(sys);
    }

    // Running out of host memory ends a run with an exception that names only what failed in C++ terms -
    // std::bad_alloc, a vector past its maximum size, a thread that could not get its stack - which
    // does not tell the user what to do. The data set is not at fault; the machine is too small for it.
    std::string FailureText(const std::exception &e) {
        const auto *sys = dynamic_cast<const std::system_error *>(&e);
        const auto *jf = dynamic_cast<const JFJochException *>(&e);
        const bool out_of_memory = dynamic_cast<const std::bad_alloc *>(&e) != nullptr
                || dynamic_cast<const std::length_error *>(&e) != nullptr
                || (sys != nullptr && sys->code() == std::errc::resource_unavailable_try_again)
                || (jf != nullptr && jf->Category() == JFJochExceptionCategory::MemAllocFailed);
        if (!out_of_memory)
            return e.what();
        return fmt::format("out of host memory ({}) - this data set needs more RAM than is available",
                           e.what());
    }
}

// FFTW ends the program itself when its allocator comes back empty (CK(p) in kernel/alloc.c) - while
// planning, or inside a buffered transform - from whichever thread that happens in, so it cannot become
// an exception. Defining its handler here keeps FFTW's own (kernel/assert.c) out of the link, and says
// what happened in the same words as every other way of running out of memory.
extern "C" void fftwf_assertion_failed(const char *s, int line, const char *file) {
    std::fflush(stdout);
    if (std::strcmp(s, "p") == 0) {
        std::fprintf(stderr, "Processing failed: out of host memory (FFTW could not allocate) - "
                             "this data set needs more RAM than is available\n");
        std::_Exit(EXIT_FAILURE);
    }
    std::fprintf(stderr, "fftw: %s:%d: assertion failed: %s\n", file, line, s);
    std::abort();
}

// The body of main. Settings setters and the pipeline itself throw JFJochException on input the parser
// cannot reject on its own (a resolution limit of zero, a distance of zero, a polarisation above one,
// an unreadable file), so main wraps this and reports rather than letting the exception terminate the
// process with no diagnostic and exit code 134.
static int RunRugnux(int argc, char **argv, bool no_gpu) {
    // cuFFT plans are reused through the run and destroyed with it, ahead of the device reset in main.
    FFTPlanReuse fft_plans;
    // The whole invocation, reported at the end and written into the results report. Started before
    // anything else so it covers reading the file and setting up as well as the processing.
    const auto invocation_start = std::chrono::steady_clock::now();
    RunProvenance provenance;
    provenance.command_line = JoinCommandLine(argc, argv);
    provenance.gpu_count = get_gpu_count();
#ifdef __APPLE__
    // Without CUDA, the Bragg integration's integer pixel work runs on the Apple GPU (MXAnalysisWithoutFPGA).
    const std::string metal_device = BraggIntegrationEngineMetal::DeviceName();
#else
    const std::string metal_device;
#endif
    provenance.gpu_description = get_gpu_description();

    // The terminal shows the run as steps (RugnuxConsole) and every Logger writes to the log file
    // instead; with -v the whole log is on the terminal as well. -v is looked for here, before the
    // options are parsed, because the parser already logs.
    bool verbose = false;
    for (int i = 1; i < argc; i++)
        if (std::strcmp(argv[i], "-v") == 0 || std::strcmp(argv[i], "--verbose") == 0)
            verbose = true;
    console = std::make_shared<RugnuxConsole>(verbose);
    std::atexit(CloseConsoleOnExit);
    // Files with an older time than this are not this run's (the margin covers coarse file times).
    const auto files_since = std::filesystem::file_time_type::clock::now() - std::chrono::seconds(2);
    auto log_sinks = std::make_shared<spdlog::sinks::dist_sink_mt>();
    // What is logged before the log file can be opened - its name comes from -o - waits here.
    auto early_log = std::make_shared<spdlog::sinks::ringbuffer_sink_mt>(10000);
    if (verbose)
        log_sinks->add_sink(std::make_shared<spdlog::sinks::stdout_color_sink_mt>());
    else
        log_sinks->add_sink(MakeConsoleSink(console));
    log_sinks->add_sink(early_log);
    Logger::RouteAll(log_sinks);
    // The HDF5 library prints its own error stack on stderr; every failure it reports reaches the
    // reader as an error code anyway, which is turned into a message there.
    H5Eset_auto2(H5E_DEFAULT, nullptr, nullptr);

    PrintBanner(*console);

    Logger logger("rugnux");
#ifdef JFJOCH_USE_CUDA
    const char *build = "CUDA build";
#else
    const char *build = "CPU build";
#endif
    logger.Info("rugnux Version {}{} - {}", jfjoch_version(),
                jfjoch_git_sha1().empty() ? std::string()
                : fmt::format(" (git {} {})", jfjoch_git_sha1().substr(0, 6), jfjoch_git_date()), build);
    logger.Info("Build flags: {}", jfjoch_build_cxx_flags().empty() ? "none" : jfjoch_build_cxx_flags());
    logger.Info("Build: {}", jfjoch_build_info(true));
    logger.Info("Command line: {}", provenance.command_line);
    logger.Info("GPU: {}", no_gpu ? std::string("not used (--no-gpu) - running on the CPU")
            : provenance.gpu_count > 0 ? fmt::format("{} ({} visible)", provenance.gpu_description, provenance.gpu_count)
            : !metal_device.empty() ? fmt::format("{} through Metal, for the Bragg integration only - the rest runs on the CPU", metal_device)
            : std::string("none visible - running on the CPU"));
    RegisterHDF5Filter();

    std::string input_file;
    std::string output_prefix = "output";
    int nthreads = 0;   // 0 = auto: resolved to the CPUs the run may use after parsing (see below)
    int start_image = 0;
    int end_image = -1; // -1 indicates process until end
    int image_stride = 1;

    RugnuxMode mode = RugnuxMode::MX;   // --mode
    std::string calibrant = "lab6";     // --calibrant
    CalibrationMethod calibration_method = CalibrationMethod::Rings;   // --calibration
    bool calibration_refine_tilt = true;   // --no-refine-tilt
    bool rotation_indexing = false;
    bool force_still = false;     // --force-still: process a rotation dataset as stills (indexing + scaling)
    bool two_pass_rotation = true;
    // Set by any spot-finding option. The two-pass rotation first pass reuses the spots stored in the
    // file when it has them, so those options would otherwise not reach the pass that determines the
    // lattice - the setting would appear to do nothing at all on rotation data.
    bool rotation_postrefine_geometry = true;   // default on; --rotation-no-postrefine disables it
    std::optional<float> rotation_scale;        // --rotation-scale: asserted stage calibration
    int rotation_indexing_image_count = RUGNUX_ROTATION_INDEXING_IMAGES;
    double prepass_fraction = 0.5;
    std::optional<float> rotation_indexing_range;
    std::optional<int64_t> min_indexed_spots;   // --min-indexed-spots: spots on the lattice for a frame to count as indexed
    bool run_scaling = true;      // merge is on by default; --no-merge turns it off
    std::optional<bool> scale_fulls_arg;   // --scale-fulls / --no-scale-fulls; default on for rot3d
    bool write_process_h5_flag = false;    // --write-process-h5; also write _process.h5 when merging
    bool simulate_live = false;            // --simulate-live
    bool fast_live = false;                // --fast-live, with --simulate-live
    bool finalist_ledger_flag = false;     // --finalist-ledger; report-only symmetry evidence table
    std::optional<bool> detect_ice_rings;  // --detect-ice-rings[=on|off]; unset => use the dataset (file) value
    bool index_ice_rings = false;          // --index-ice-rings[=on|off]; index on the ice-band spots too
    std::optional<double> ice_min_score_arg;   // --ice-min-score: ice-presence gate on the measured score
    std::optional<double> ice_min_spot_ratio_arg;   // --ice-min-spot-ratio: the same gate on the spot channel
    std::optional<float> fft_min_unit_cell_A;   // --fft-min-unit-cell: shortest axis the FFT search accepts
    std::optional<float> min_q, max_q, q_spacing;   // azimuthal integration range / -q spacing (1/A)
    std::optional<int32_t> azimuthal_bins;          // --azimuthal-bins
    std::optional<bool> polarization_correction;    // --polarization-correction (azimuthal integration)
    std::optional<bool> solid_angle_correction;     // --solid-angle-correction (azimuthal integration)
    std::optional<FlightPathMedium> flight_path;    // --flight-path (Bragg prediction)

    // Geometry overrides (default: keep the value stored in the input file)
    std::optional<float> beam_x, beam_y, detector_distance_mm, wavelength_A, rot1_rad, rot2_rad, rot3_rad, polarization_factor;
    bool detector_mirror_y = false;
    int64_t detector_quarter_turns = 0;
    std::optional<double> smooth_g_deg_arg;   // --smooth-g[=deg]; default 5 deg for rot3d, 0 (off) otherwise
    std::optional<double> relative_b_deg_arg; // --relative-b[=deg]; per-batch relative-B width, 0 (off) unless given
    bool no_scaling_corrections = false;   // --no-scaling-corrections: disable rot3d decay+absorption+modulation surfaces
    bool no_expected_variance_merge = false;  // --no-expected-variance-merge: restore observed-sigma stills merge weighting
    bool anomalous_mode = false;
    const gemmi::SpaceGroup *space_group = nullptr;
    std::optional<UnitCell> fixed_reference_unit_cell;
    std::optional<int64_t> max_spot_count_override;
    float sigma_spot_finding = SpotFindingSettings{}.signal_to_noise_threshold;
    int64_t photon_count_threshold_spot_finding = SpotFindingSettings{}.photon_count_threshold;
    std::optional<int64_t> min_pix_per_spot;   // unset -> adaptive per image; a value -> fixed min-pix
    std::optional<bool> adaptive_spots;   // unset -> on, for both workflows
    float false_pixels_per_frame = SpotFindingSettings{}.false_pixels_per_frame;
    std::string ref_mtz;
    std::string ref_column;
    std::string crystfel_geometry;   // --crystfel-geometry: read the input as CrystFEL would with this geometry
    std::string model_pdb;           // --model: PDB to validate merged intensities against (R-free + maps)
    std::string mr_model;            // --mr: --model, placed by molecular replacement straight away
    bool export_unmerged = true;            // on by default; --no-export-unmerged turns it off
    bool export_unmerged_partials = false;  // --export-unmerged-partials: the same, one row per image
    std::string dump_observations;   // diagnostic: dump unmerged -P rot3d fulls to this path
    double min_partiality = 0.02;
    std::optional<double> min_captured_fraction_arg;   // explicit --min-captured-fraction; default depends on rotation
    std::optional<double> capture_uncertainty_arg;   // explicit --capture-uncertainty; default depends on rot3d
    std::optional<double> forced_mosaicity_arg;      // diagnostic: fix the scaling mosaicity (deg) instead of the per-image seed
    std::optional<double> forced_prediction_mosaicity_arg;  // diagnostic: fix the PREDICTION mosaicity (deg), leaving the partiality on the per-image value
    double min_image_cc = 0.0;
    std::optional<double> search_min_zeta_arg;   // --search-min-zeta; rotation default below
    int64_t scaling_iter = 100;
    std::optional<CrystalLattice> forced_rotation_lattice;
    std::optional<double> background_clip_arg;         // --background-clip: background-ring high-side sigma clip
    std::optional<bool> background_radial_arg;         // set = force on/off, unset = auto (the default)
    std::optional<int> detect_beam_stop = RUGNUX_DETECT_BEAM_STOP_FRAMES;  // --detect-beam-stop[=N|off]; on by default
    bool beam_center_check = true;             // --beam-center-check[=off]; on by default
    std::optional<int> refine_geometry;   // --refine-geometry[=N]: stills global geometry-refinement pass
    bool refine_geometry_disabled = false; // --refine-geometry=off: opt out of the stills default-on

    std::optional<float> bandwidth_fwhm; // relative FWHM of dlambda/lambda

    IndexingAlgorithmEnum indexing_algorithm = IndexingAlgorithmEnum::Auto;
    GeomRefinementAlgorithmEnum refinement_algorithm = GeomRefinementAlgorithmEnum::BeamCenter;

    std::optional<float> d_min_spot_finding;    // unset -> as far as the detector reaches
    // The low-resolution limit to apply: starts at the SpotFindingSettings default rather than restating
    // it, and --spot-low-resolution 0 resets it to unset, i.e. no limit at that end.
    std::optional<float> d_max_spot_finding = SpotFindingSettings{}.low_resolution_limit;
    std::optional<float> d_min_scale_merge;
    std::optional<float> d_max_scale_merge;   // --scaling-low-resolution; 0 removes the default limit
    std::optional<ResolutionCutoffMethod> resolution_cutoff_method;   // --resolution-cutoff cc-logistic|off
    std::optional<double> resolution_cc_target;                      // --resolution-cc-target
    std::optional<int> report_shell_count;                           // --resolution-shells
    std::optional<std::string> report_resolution_arg;                // --report-resolution
    std::optional<std::string> integration_radius_arg;
    // --adaptive-integration-radius: unset means the per-workflow default below (on for rotation).
    std::optional<bool> adaptive_integration_radius_arg;
    std::optional<std::string> integration_stencil_arg; // --integration-stencil: ring elongation, in sigma
    std::optional<double> background_trim_arg;         // --background-trim: background-ring trimmed-mean fraction
    std::optional<OverlapMode> overlap_arg;            // --overlap: treatment of shared signal pixels
    std::optional<double> overlap_minpk_arg;           // --overlap-minpk: XDS-like MINPK threshold
    std::optional<int64_t> max_hkl_arg;                // --max-hkl: half-width of the predicted hkl box
    std::optional<double> integration_d_min_arg;       // --integration-high-resolution; unset = detector reach
    std::optional<IntegratorMode> integrator_mode;     // --integrator boxsum|gaussian|empirical
    bool simple_stills_flag = false;                   // --simple-stills: disable the default stills partiality post-refinement
    std::optional<double> outlier_reject_nsigma;       // merge per-observation outlier rejection

    if (argc == 1) {
        print_usage();
        exit(EXIT_FAILURE);
    }

    int opt;
    int option_index = 0;
    const char *short_opts = "vo:N:s:e:t:R::X:C:z:FAS:r:q:";

  while ((opt = getopt_long(argc, argv, short_opts, long_options, &option_index)) != -1) {
    switch (opt) {
        case 'o':
            output_prefix = optarg;
            break;
        case 'v':
            verbose = true;
            break;
        case 'N':
            nthreads = atoi(optarg);
            break;
        case 's':
            start_image = atoi(optarg);
            break;
        case 'e':
            end_image = atoi(optarg);
            break;
        case 't':
            image_stride = atoi(optarg);
            break;
        case 'R':
            if (rotation_indexing) {
                logger.Error("Rotation indexing already enabled");
                exit(EXIT_FAILURE);
            }
            rotation_indexing = true;
            two_pass_rotation = true;
            if (optarg)
                rotation_indexing_image_count = atoi(optarg);

            break;
        case OPT_SINGLE_PASS_ROTATION:
            if (rotation_indexing) {
                logger.Error("Rotation indexing already enabled");
                exit(EXIT_FAILURE);
            }
            rotation_indexing = true;
            two_pass_rotation = false;

            if (optarg)
                rotation_indexing_range = atof(optarg);
            break;
        case OPT_ROTATION_NO_POSTREFINE:
            rotation_postrefine_geometry = false;
            break;
        case OPT_PREPASS_FRACTION:
            prepass_fraction = parse_number_arg<double>(optarg, "--prepass-fraction", logger, 0.05, 1.0);
            break;
        case OPT_ROTATION_SCALE:
            rotation_scale = parse_number_arg<float>(optarg, "--rotation-scale", logger, 0.9f, 1.1f);
            break;
        case OPT_MIN_INDEXED_SPOTS:
            min_indexed_spots = parse_number_arg<int64_t>(optarg, "--min-indexed-spots", logger);
            break;
        case OPT_DETECT_BEAM_STOP:
            // Frames projected to find the shadow. The default is what the detection was validated
            // on; fewer leaves the background too sparsely counted to tell a shadow from noise.
            if (optarg && std::string(optarg) == "off") {
                detect_beam_stop = std::nullopt;
                break;
            }
            detect_beam_stop = optarg
                ? parse_number_arg<int>(optarg, "--detect-beam-stop", logger, 1, 1000000)
                : RUGNUX_DETECT_BEAM_STOP_FRAMES;
            break;
        case OPT_BEAM_CENTER_CHECK:
            beam_center_check = !optarg || std::string(optarg) != "off";
            break;
        case OPT_REFINE_GEOMETRY: {
            if (optarg && std::string(optarg) == "off") {
                refine_geometry = std::nullopt;
                refine_geometry_disabled = true;   // opt out of the stills default-on
                break;
            }
            // Positive frame count fed to the bundle adjust; upper-bounded so refine_frames * 50 in
            // RefineStillsGeometry cannot overflow int (1e6 is already far past any real dataset).
            refine_geometry = optarg
                ? parse_number_arg<int>(optarg, "--refine-geometry", logger, 1, 1000000)
                : RUGNUX_REFINE_GEOMETRY_FRAMES;
            break;
        }
        case OPT_FORCE_ROTATION_LATTICE: {
            if (rotation_indexing) {
                logger.Error("Rotation indexing already enabled");
                exit(EXIT_FAILURE);
            }
            rotation_indexing = true;

            auto latt = parse_lattice_arg(optarg);
            if (!latt.has_value()) {
                logger.Error(
                    "Invalid rotation lattice. Expected: \"a0x,a0y,a0z,a1x,a1y,a1z,a2x,a2y,a2z\" (9 floats, comma-separated). Got: {}",
                    optarg ? optarg : "<null>");
                print_usage();
                exit(EXIT_FAILURE);
            }
            forced_rotation_lattice = latt;
            auto uc = latt->GetUnitCell();
            logger.Info(
                "Forced rotation lattice set: a={:.3f} b={:.3f} c={:.3f} alpha={:.3f} beta={:.3f} gamma={:.3f}",
                uc.a, uc.b, uc.c, uc.alpha, uc.beta, uc.gamma);
            break;
        }
        case 'X': {
            std::string alg = optarg ? optarg : "";
            std::transform(alg.begin(), alg.end(), alg.begin(),
                           [](unsigned char c) { return static_cast<char>(std::tolower(c)); });

            if (alg == "ffbidx")
                indexing_algorithm = IndexingAlgorithmEnum::FFBIDX;
            else if (alg == "fft")   // the algorithm: on the GPU where there is one, else with FFTW
                indexing_algorithm = get_gpu_count() > 0 ? IndexingAlgorithmEnum::FFT : IndexingAlgorithmEnum::FFTW;
            else if (alg == "cufft")
                indexing_algorithm = IndexingAlgorithmEnum::FFT;
            else if (alg == "fftw")
                indexing_algorithm = IndexingAlgorithmEnum::FFTW;
            else if (alg == "auto")
                indexing_algorithm = IndexingAlgorithmEnum::Auto;
            else if (alg == "none")
                indexing_algorithm = IndexingAlgorithmEnum::None;
            else {
                logger.Error("Invalid indexing algorithm: {}", alg);
                print_usage();
                exit(EXIT_FAILURE);
            }
            break;
        }
        case 'r': {
            std::string alg = optarg ? optarg : "";
            std::transform(alg.begin(), alg.end(), alg.begin(),
                           [](unsigned char c) { return static_cast<char>(std::tolower(c)); });
            if (alg == "none")
                refinement_algorithm = GeomRefinementAlgorithmEnum::None;
            else if (alg == "beam_and_lattice")
                refinement_algorithm = GeomRefinementAlgorithmEnum::BeamCenter;
            else if (alg == "orientation")
                refinement_algorithm = GeomRefinementAlgorithmEnum::OrientationOnly;
            else if (alg == "flex" || alg == "multi")   // "multi" kept as a back-compat alias
                refinement_algorithm = GeomRefinementAlgorithmEnum::Flex;
            else {
                logger.Error("Invalid geom refinement algorithm: {}", alg);
                print_usage();
                exit(EXIT_FAILURE);
            }
            break;
        }
        case 'C': {
            auto uc = parse_unit_cell_arg(optarg);
            if (!uc.has_value()) {
                logger.Error(
                    "Invalid unit cell. Expected: \"a,b,c,alpha,beta,gamma\" (6 floats, comma-separated, no spaces). Got: {}",
                    optarg ? optarg : "<null>");
                print_usage();
                exit(EXIT_FAILURE);
            }
            fixed_reference_unit_cell = uc;
            logger.Info(
                "Fixed reference unit cell set: a={:.3f} b={:.3f} c={:.3f} alpha={:.3f} beta={:.3f} gamma={:.3f}",
                uc->a, uc->b, uc->c, uc->alpha, uc->beta, uc->gamma);
            break;
        }
        case 'z':
            ref_mtz = optarg;
            break;
        case OPT_REFERENCE_COLUMN:
            ref_column = optarg;
            break;
        case OPT_MODEL:
            model_pdb = optarg;
            break;
        case OPT_CRYSTFEL_GEOMETRY:
            crystfel_geometry = optarg;
            break;
        case OPT_MR:
            mr_model = optarg;
            break;
        case OPT_EXPORT_UNMERGED:
            export_unmerged = true;
            break;
        case OPT_NO_EXPORT_UNMERGED:
            export_unmerged = false;
            break;
        case OPT_EXPORT_UNMERGED_PARTIALS:
            export_unmerged_partials = true;
            break;
        case OPT_DUMP_OBSERVATIONS:
            dump_observations = optarg;
            break;
        case 'F':
            indexing_algorithm = get_gpu_count() > 0 ? IndexingAlgorithmEnum::FFT : IndexingAlgorithmEnum::FFTW;
            break;
        case 'A':
            anomalous_mode = true;
            break;
        case 'S': {
            // Accept a space-group number ("96") or a Hermann-Mauguin symbol ("P43212", "P 43 21 2").
            // The symbol is kept as the group it names, not reduced to its number: a number can only
            // ever name the reference setting, so -S P1121 would silently become P 1 21 1.
            char *end = nullptr;
            const long as_number = strtol(optarg, &end, 10);
            space_group = (end != optarg && *end == '\0')
                ? gemmi::find_spacegroup_by_number(static_cast<int>(as_number))
                : gemmi::find_spacegroup_by_name(optarg);
            if (space_group == nullptr) {
                logger.Error("Unknown space group '{}' (use a number like 96 or a symbol like P43212)", optarg);
                exit(EXIT_FAILURE);
            }
            break;
        }
        case OPT_SPOT_SIGMA:
            sigma_spot_finding = parse_number_arg<float>(optarg, "--spot-sigma", logger, 1.0f);
            logger.Info("Noise threshold level for spot finding set to {:.2f} sigma", sigma_spot_finding);
            break;
        case OPT_SPOT_THRESHOLD:
            photon_count_threshold_spot_finding = parse_number_arg<int64_t>(optarg, "--spot-threshold", logger, 0);
            logger.Info("Photon-count threshold level for spot finding set to {:d}",
                        photon_count_threshold_spot_finding);
            break;
        case OPT_MIN_PIX_PER_SPOT:
            // Giving an explicit min-pix opts out of the per-image adaptive selection.
            min_pix_per_spot = parse_number_arg<int64_t>(optarg, "--min-pix-per-spot", logger, 1);
            logger.Info("Minimum pixels per spot fixed at {:d} (adaptive per-image min-pix off)", *min_pix_per_spot);
            break;
        case OPT_ADAPTIVE_SPOTS:
            adaptive_spots = true;
            logger.Info("Adaptive (self-calibrating) spot detection enabled");
            break;
        case OPT_NO_ADAPTIVE_SPOTS:
            adaptive_spots = false;
            logger.Info("Adaptive spot detection off: using the fixed --spot-threshold / --spot-sigma finder");
            break;
        case OPT_SPOT_FALSE_PIXELS:
            false_pixels_per_frame = parse_number_arg<float>(optarg, "--spot-false-pixels", logger, 1.0f);
            adaptive_spots = true;
            logger.Info("Adaptive spot detection: expected false pixels/frame set to {:.0f}", false_pixels_per_frame);
            break;
        case OPT_SPOT_LOW_RESOLUTION: {
            // Same shape as --spot-high-resolution below: 0 means "no limit at that end", expressed as
            // the unset optional the rest of the code understands.
            const auto d_max = parse_number_arg<float>(optarg, "--spot-low-resolution", logger, 0.0f);
            if (d_max > 0.0f) {
                d_max_spot_finding = d_max;
                logger.Info("Low resolution limit for spot finding set to {:.1f} A", d_max);
            } else {
                d_max_spot_finding.reset();
                logger.Info("No low resolution limit for spot finding");
            }
            break;
        }
        case OPT_SPOT_RESOLUTION: {
            // 0 has always meant "no limit" for this setting; keep that, but express it as the unset
            // optional the rest of the code understands. Passing the 0 through instead reached
            // ResolutionShells (via the spot plot), which rejects a zero d_min and threw away every image.
            const auto d_min = parse_number_arg<float>(optarg, "--spot-high-resolution", logger, 0.0f);
            if (d_min > 0.0f) {
                d_min_spot_finding = d_min;
                logger.Info("High resolution limit for spot finding set to {:.2f} A", d_min);
            } else {
                d_min_spot_finding.reset();
                logger.Info("No high resolution limit for spot finding: as far as the detector reaches");
            }
            break;
        }
        case OPT_MAX_SPOTS:
            max_spot_count_override = parse_number_arg<int64_t>(optarg, "--max-spots", logger, 1);
            break;
        case OPT_MODE: {
            const std::string m = optarg ? optarg : "";
            if (m == "mx") mode = RugnuxMode::MX;
            else if (m == "azint") mode = RugnuxMode::Azint;
            else if (m == "scale") mode = RugnuxMode::Scale;
            else if (m == "calibration") mode = RugnuxMode::Calibration;
            else {
                logger.Error("Invalid --mode: {} (expected mx|azint|scale|calibration)", m);
                return 1;
            }
            break;
        }
        case OPT_CALIBRANT:
            calibrant = optarg ? optarg : "";
            if (CalibrantRings(calibrant).empty()) {
                logger.Error("Unknown --calibrant: {} (expected {})", calibrant, CalibrantNameList());
                return 1;
            }
            break;
        case OPT_CALIBRATION:
            if (strcmp(optarg, "rings") == 0) calibration_method = CalibrationMethod::Rings;
            else if (strcmp(optarg, "spots") == 0) calibration_method = CalibrationMethod::Spots;
            else {
                logger.Error("Invalid --calibration: {} (expected rings|spots)", optarg);
                return 1;
            }
            break;
        case OPT_NO_REFINE_TILT:
            calibration_refine_tilt = false;
            break;
        case OPT_NO_MERGE:
            run_scaling = false;
            break;
        case OPT_SCALE_FULLS:
            scale_fulls_arg = true;
            break;
        case OPT_NO_SCALE_FULLS:
            scale_fulls_arg = false;
            break;
        case OPT_DETECT_ICE_RINGS:
            if (optarg == nullptr || strcmp(optarg, "on") == 0)
                detect_ice_rings = true;
            else if (strcmp(optarg, "off") == 0)
                detect_ice_rings = false;
            else {
                logger.Error("Invalid --detect-ice-rings value: {} (expected on|off)", optarg);
                print_usage();
                exit(EXIT_FAILURE);
            }
            break;
        case OPT_INDEX_ICE_RINGS:
            if (optarg == nullptr || strcmp(optarg, "on") == 0)
                index_ice_rings = true;
            else if (strcmp(optarg, "off") == 0)
                index_ice_rings = false;
            else {
                logger.Error("Invalid --index-ice-rings value: {} (expected on|off)", optarg);
                print_usage();
                exit(EXIT_FAILURE);
            }
            break;
        case OPT_ICE_MIN_SCORE:
            ice_min_score_arg = parse_double_arg(optarg, "--ice-min-score", logger);
            break;
        case OPT_ICE_MIN_SPOT_RATIO:
            ice_min_spot_ratio_arg = parse_double_arg(optarg, "--ice-min-spot-ratio", logger);
            break;
        case OPT_WRITE_PROCESS_H5:
            write_process_h5_flag = true;
            break;
        case OPT_FINALIST_LEDGER:
            finalist_ledger_flag = true;
            break;
        case OPT_FAST_LIVE:
            fast_live = true;
            break;
        case OPT_SIMULATE_LIVE:
            simulate_live = true;
            simulated_frame_time = std::chrono::microseconds(
                    std::lround(1000.0 * parse_double_arg(optarg, "--simulate-live", logger)));
            break;
        case OPT_DEVELOPER:
            provenance.developer = true;
            break;
        case OPT_NO_GPU:   // acted on in main, before anything asks CUDA for the devices
            break;
        case OPT_SMOOTH_G:
            smooth_g_deg_arg = optarg ? parse_double_arg(optarg, "--smooth-g", logger) : SMOOTH_G_DEFAULT_DEG;
            break;
        case OPT_RELATIVE_B:
            relative_b_deg_arg = optarg ? parse_double_arg(optarg, "--relative-b", logger) : RELATIVE_B_DEFAULT_DEG;
            break;
        case OPT_NO_EXPECTED_VARIANCE_MERGE:
            no_expected_variance_merge = true;
            break;
        case OPT_NO_SCALING_CORRECTIONS:
            no_scaling_corrections = true;
            break;
        case OPT_MIN_PARTIALITY:
            min_partiality = parse_double_arg(optarg, "--min-partiality", logger);
            break;
        case OPT_CAPTURE_UNCERTAINTY:
            capture_uncertainty_arg = parse_double_arg(optarg, "--capture-uncertainty", logger);
            break;
        case OPT_MIN_CAPTURED_FRACTION:
            min_captured_fraction_arg = parse_double_arg(optarg, "--min-captured-fraction", logger);
            break;
        case OPT_MOSAICITY:
            forced_mosaicity_arg = parse_double_arg(optarg, "--mosaicity", logger);
            break;
        case OPT_PREDICTION_MOSAICITY:
            forced_prediction_mosaicity_arg = parse_double_arg(optarg, "--prediction-mosaicity", logger);
            break;
        case OPT_INTEGRATION_RADIUS:
            integration_radius_arg = optarg;
            break;
        case OPT_ADAPTIVE_INTEGRATION_RADIUS:
            adaptive_integration_radius_arg = !optarg || std::string(optarg) != "off";
            break;
        case OPT_INTEGRATION_STENCIL:
            integration_stencil_arg = optarg;
            break;
        case OPT_BACKGROUND_TRIM:
            background_trim_arg = parse_double_arg(optarg, "--background-trim", logger);
            break;
        case OPT_OVERLAP:
            if (strcmp(optarg, "off") == 0) overlap_arg = OverlapMode::Off;
            else if (strcmp(optarg, "reject") == 0) overlap_arg = OverlapMode::Reject;
            else if (strcmp(optarg, "exclude") == 0) overlap_arg = OverlapMode::Exclude;
            else { logger.Error("--overlap expects off|reject|exclude"); return 1; }
            break;
        case OPT_OVERLAP_MINPK:
            overlap_minpk_arg = parse_double_arg(optarg, "--overlap-minpk", logger);
            break;
        case OPT_MAX_HKL:
            max_hkl_arg = parse_number_arg<int64_t>(optarg, "--max-hkl", logger, 1, 511);
            break;
        case OPT_INTEGRATION_HIGH_RES:
            integration_d_min_arg = parse_double_arg(optarg, "--integration-high-resolution", logger);
            break;
        case OPT_BACKGROUND_RADIAL:
            if (optarg == nullptr || strcmp(optarg, "on") == 0)
                background_radial_arg = true;
            else if (strcmp(optarg, "off") == 0)
                background_radial_arg = false;
            else if (strcmp(optarg, "auto") == 0)
                background_radial_arg = std::nullopt;
            else {
                logger.Error("Invalid --background-radial value: {} (expected on|off|auto)", optarg);
                return 1;
            }
            break;
        case OPT_BACKGROUND_CLIP:
            background_clip_arg = parse_double_arg(optarg, "--background-clip", logger);
            break;
        case OPT_INTEGRATOR:
            if (strcmp(optarg, "boxsum") == 0) integrator_mode = IntegratorMode::BoxSum;
            else if (strcmp(optarg, "gaussian") == 0) integrator_mode = IntegratorMode::ProfileGaussian;
            else if (strcmp(optarg, "empirical") == 0) integrator_mode = IntegratorMode::ProfileEmpirical;
            else { logger.Error("--integrator expects boxsum|gaussian|empirical"); return 1; }
            break;
        case OPT_SIMPLE_STILLS:
            simple_stills_flag = true;
            break;
        case OPT_REJECT_OUTLIERS:
            outlier_reject_nsigma = parse_double_arg(optarg, "--reject-outliers", logger);
            break;
        case OPT_MIN_IMAGE_CC:
            min_image_cc = parse_double_arg(optarg, "--min-image-cc", logger);
            break;
        case OPT_SEARCH_MIN_ZETA:
            search_min_zeta_arg = parse_double_arg(optarg, "--search-min-zeta", logger);
            break;
        case OPT_SCALING_HIGH_RESOLUTION:
            d_min_scale_merge = parse_number_arg<float>(optarg, "--scaling-high-resolution", logger,
                                                       0.1f, 1000.0f);
            break;
        case OPT_SCALING_LOW_RESOLUTION:
            d_max_scale_merge = parse_number_arg<float>(optarg, "--scaling-low-resolution", logger,
                                                        0.0f, 100000.0f);
            break;
        case OPT_RESOLUTION_CUTOFF:
            if (strcmp(optarg, "cc-logistic") == 0)
                resolution_cutoff_method = ResolutionCutoffMethod::CCHalfLogistic;
            else if (strcmp(optarg, "off") == 0)
                resolution_cutoff_method = ResolutionCutoffMethod::Off;
            else {
                logger.Error("Invalid --resolution-cutoff value: {} (expected cc-logistic|off)", optarg);
                print_usage();
                exit(EXIT_FAILURE);
            }
            break;
        case OPT_RESOLUTION_CC_TARGET:
            resolution_cc_target = parse_double_arg(optarg, "--resolution-cc-target", logger);
            break;
        case OPT_REPORT_RESOLUTION:
            report_resolution_arg = optarg;
            break;
        case OPT_RESOLUTION_SHELLS:
            report_shell_count = atoi(optarg);
            if (report_shell_count.value() < 1) {
                logger.Error("Invalid --resolution-shells value: {} (must be >= 1)", report_shell_count.value());
                exit(EXIT_FAILURE);
            }
            break;
        case OPT_FORCE_STILL:
            force_still = true;
            break;
        case 'q':
            q_spacing = atof(optarg);
            break;
        case OPT_AZIM_MIN_Q:
            min_q = atof(optarg);
            break;
        case OPT_AZIM_MAX_Q:
            max_q = atof(optarg);
            break;
        case OPT_AZIM_PHI_BINS:
            azimuthal_bins = atoi(optarg);
            break;
        case OPT_POLARIZATION_CORRECTION: {
            bool value;
            if (!parse_on_off(optarg, value)) {
                logger.Error("Invalid polarization correction value (expected on|off): {}", optarg);
                exit(EXIT_FAILURE);
            }
            polarization_correction = value;
            break;
        }
        case OPT_SOLID_ANGLE_CORRECTION: {
            bool value;
            if (!parse_on_off(optarg, value)) {
                logger.Error("Invalid solid angle correction value (expected on|off): {}", optarg);
                exit(EXIT_FAILURE);
            }
            solid_angle_correction = value;
            break;
        }
        case OPT_FLIGHT_PATH: {
            const std::string v = optarg;
            if (v == "air") flight_path = FlightPathMedium::Air;
            else if (v == "helium" || v == "he") flight_path = FlightPathMedium::Helium;
            else if (v == "vacuum") flight_path = FlightPathMedium::Vacuum;
            else {
                logger.Error("Invalid flight path (expected air|helium|vacuum): {}", optarg);
                exit(EXIT_FAILURE);
            }
            break;
        }
        case OPT_BEAM_X: beam_x = parse_float_arg(optarg, "--beam-x", logger); break;
        case OPT_BEAM_Y: beam_y = parse_float_arg(optarg, "--beam-y", logger); break;
        case OPT_DETECTOR_DISTANCE: detector_distance_mm = parse_float_arg(optarg, "--detector-distance", logger); break;
        case OPT_WAVELENGTH: {
            // Guard > 0: wavelength is used as a divisor (WVL_1A_IN_KEV / wavelength) below, and a 0
            // would produce a non-finite incident energy that throws unguarded and aborts the process.
            float w = parse_float_arg(optarg, "--wavelength", logger);
            if (!(w > 0.0f)) {
                logger.Error("Invalid wavelength (must be > 0 A): {}", optarg);
                exit(EXIT_FAILURE);
            }
            wavelength_A = w;
            break;
        }
        case OPT_ROT1: rot1_rad = parse_float_arg(optarg, "--rot1", logger); break;
        case OPT_ROT2: rot2_rad = parse_float_arg(optarg, "--rot2", logger); break;
        case OPT_ROT3: rot3_rad = parse_float_arg(optarg, "--rot3", logger); break;
        case OPT_DETECTOR_MIRROR_Y: detector_mirror_y = true; break;
        case OPT_DETECTOR_QUARTER_TURNS:
            detector_quarter_turns = atoi(optarg);
            if (detector_quarter_turns < 0 || detector_quarter_turns > 3) {
                logger.Error("--detector-quarter-turns must be 0, 1, 2 or 3");
                return 1;
            }
            break;
        case OPT_FFT_MIN_UNIT_CELL:
            fft_min_unit_cell_A = parse_float_arg(optarg, "--fft-min-unit-cell", logger); break;
        case OPT_POLARIZATION: polarization_factor = parse_float_arg(optarg, "--polarization", logger); break;
        case OPT_SCALING_ITERATIONS:
            scaling_iter = atoi(optarg);
            if (scaling_iter <= 0) {
                logger.Error("Invalid scaling iteration count: {}", scaling_iter);
                exit(EXIT_FAILURE);
            }
            break;
        case OPT_BANDWIDTH:
            bandwidth_fwhm = atof(optarg);
            if (!(bandwidth_fwhm.value() >= 0.0f)) {
                logger.Error("Invalid bandwidth: {}", optarg);
                exit(EXIT_FAILURE);
            }
            break;

        default:
            print_usage();
            exit(EXIT_FAILURE);
    }
}

    if (optind != argc - 1 && optind != argc - 2) {
        logger.Error("Input file not specified");
        print_usage();
        exit(EXIT_FAILURE);
    }

    if (!mr_model.empty() && mode != RugnuxMode::MX) {
        logger.Error("--mr is for --mode mx only");
        exit(EXIT_FAILURE);
    }
    if (!mr_model.empty() && !model_pdb.empty()) {
        logger.Error("--model and --mr both name the model; give one");
        exit(EXIT_FAILURE);
    }
    // Read before anything runs: a file that holds no model ends the run here rather than after it.
    std::shared_ptr<const RugnuxModel> model;
    if (const std::string path = mr_model.empty() ? model_pdb : mr_model; !path.empty()) {
        try {
            model = std::make_shared<const RugnuxModel>(ReadRugnuxModelFile(path));
        } catch (const std::exception &e) {
            logger.Error("Cannot read the model {}: {}", path, e.what());
            exit(EXIT_FAILURE);
        }
    }

    if ((indexing_algorithm == IndexingAlgorithmEnum::FFT || indexing_algorithm == IndexingAlgorithmEnum::FFBIDX)
        && get_gpu_count() == 0) {
        logger.Error("-X {} runs on the GPU only, and {}; -X FFT or Auto index on the CPU",
                     indexing_algorithm == IndexingAlgorithmEnum::FFT ? "cuFFT" : "FFBIDX",
                     no_gpu ? "--no-gpu is given" : "no GPU is visible");
        exit(EXIT_FAILURE);
    }

    input_file = argv[optind];
    const std::string broker_url = (optind == argc - 2) ? argv[optind + 1] : "";

    // -N defaults to 0 = "use every CPU the run may use" (AvailableCpus); resolve it to a concrete count here so every mode
    // behaves the same. The scale/merge engines expand 0 on their own, but the per-image processing
    // loop (Rugnux) spawns exactly nthreads workers, so passing 0 there would spawn none and process
    // nothing - hence resolving it centrally rather than relying on each consumer.
    // Left to choose, a run on a machine of several sockets also keeps to the sockets its cards are on,
    // and takes their CPUs (ConfineToGpuPackages).
    const bool nthreads_auto = nthreads <= 0;
    std::vector<int> confined_cpus;
    if (nthreads_auto) {
        confined_cpus = ConfineToGpuPackages(get_gpu_numa_nodes());
        nthreads = static_cast<int>(AvailableCpus());
    }

    // The log file, next to the outputs, and everything logged so far into it.
    std::string &log_file = g_log_file;
    if (!output_prefix.empty()) {
        log_file = output_prefix + "_log.txt";
        try {
            auto file = std::make_shared<spdlog::sinks::basic_file_sink_mt>(log_file, /*truncate=*/true);
            for (const auto &m : early_log->last_raw())
                file->log(m);
            log_sinks->add_sink(file);
        } catch (const std::exception &e) {
            logger.Warning("The log file {} cannot be written: {}", log_file, e.what());
            log_file.clear();
        }
    }
    log_sinks->remove_sink(early_log);
    if (!confined_cpus.empty()) {
        std::string list;   // "24-35,72-83"
        for (size_t i = 0; i < confined_cpus.size();) {
            size_t j = i;
            while (j + 1 < confined_cpus.size() && confined_cpus[j + 1] == confined_cpus[j] + 1)
                j++;
            list += (list.empty() ? "" : ",") + std::to_string(confined_cpus[i])
                    + (j > i ? "-" + std::to_string(confined_cpus[j]) : "");
            i = j + 1;
        }
        logger.Info("Threads: {} (the CPUs of the GPUs' sockets: {})", nthreads, list);
    } else
        logger.Info("Threads: {}{}", nthreads, nthreads_auto ? " (the CPUs this run may use)" : " (-N)");

    console->Field("Input", input_file);
    console->Field("Output", log_file.empty() ? output_prefix + "_*"
                                              : fmt::format("{}_*   (full log in {})", output_prefix, log_file));
    // Said before the run rather than after it: the GPUs are what makes rugnux fast, and a machine
    // that turns out to have none - a driver mismatch, a CUDA_VISIBLE_DEVICES left over from another
    // job - is worth knowing about while there is still time to stop and fix it.
    console->Field("Compute", no_gpu ? fmt::format("CPU only (--no-gpu), {} threads", nthreads)
            : provenance.gpu_count > 0
            ? fmt::format("{}, {} threads", provenance.gpu_description, nthreads)
            : !metal_device.empty()
            ? fmt::format("{} CPU threads, Bragg integration on {} (Metal)", nthreads, metal_device)
            : fmt::format("no GPU visible - {} CPU threads, which is much slower", nthreads));
    console->Rule('-');

    if (space_group != nullptr)
        logger.Info("Using space group {} (number {})", space_group->hm, space_group->number);

    // Off the critical path, so cuFFT's one-time initialisation overlaps the file open, the mask read
    // and the beam-stop pre-scan instead of landing inside the first pass. It also times a plan, which
    // shows whether the CUDA JIT cache works.
    auto cufft_warmup = std::async(std::launch::async, [&logger] { LogCudaJitCache(logger, WarmUpCuFFT()); });
    // The same for the CUDA contexts of the other cards (the warm-up above creates card 0's), which
    // the pre-scan does not use: created one after another at start-up, they cost a fifth of a second
    // per card before the run began.
    auto context_warmup = std::async(std::launch::async, create_gpu_contexts, 1);

    // 1. Read Input File. An HDF5 master, one PILATUS miniCBF frame, or one marCCD frame - naming
    // any frame of a sweep reads the whole sweep, which is how these are archived and how a user
    // thinks of them.
    console->OnStep("Reading input");
    SimulatedLive<JFJochHDF5Reader> hdf5_reader;
    SimulatedLive<JFJochCBFReader> cbf_reader;
    SimulatedLive<JFJochMarCCDReader> marccd_reader;
    SimulatedLive<JFJochSMVReader> smv_reader;
    SimulatedLive<JFJochCrystFELReader> crystfel_reader;
    SimulatedLive<JFJochXTCReader> xtc_reader;
    JFJochStartMessageReader live_reader;
    std::unique_ptr<BrokerFeed> broker_feed;
    JFJochReader *reader_ptr = nullptr;
    // Which format this is. Asked INSIDE the try: these open and read the file - a directory whose
    // first plausible member cannot be read throws here - and an input the program cannot read has to
    // come out as the message below, not as an unhandled exception with nothing printed at all.
    bool input_is_cbf = false, input_is_marccd = false, input_is_smv = false, input_is_crystfel = false;
    bool input_is_xtc = false;
    try {
        input_is_crystfel = !crystfel_geometry.empty();
        input_is_cbf = !input_is_crystfel && JFJochCBFReader::CanRead(input_file);
        input_is_marccd = !input_is_cbf && JFJochMarCCDReader::CanRead(input_file);
        input_is_smv = !input_is_cbf && !input_is_marccd && JFJochSMVReader::CanRead(input_file);
        input_is_xtc = !input_is_crystfel && !input_is_cbf && !input_is_marccd && !input_is_smv
                       && JFJochXTCReader::CanRead(input_file);
        if (input_is_crystfel) {
            crystfel_reader.ReadFiles(input_file, crystfel_geometry);
            reader_ptr = &crystfel_reader;
            logger.Info("Read {} frames from {} with the CrystFEL geometry {}",
                        crystfel_reader.GetNumberOfImages(), input_file, crystfel_geometry);
        } else if (input_is_cbf) {
            cbf_reader.ReadFiles(input_file);
            reader_ptr = &cbf_reader;
            logger.Info("Read {} CBF images of the sweep containing {}",
                        cbf_reader.GetNumberOfImages(), input_file);
        } else if (input_is_marccd) {
            marccd_reader.ReadFiles(input_file);
            reader_ptr = &marccd_reader;
            logger.Info("Read {} marCCD images of the sweep containing {}",
                        marccd_reader.GetNumberOfImages(), input_file);
        } else if (input_is_smv) {
            smv_reader.ReadFiles(input_file);
            reader_ptr = &smv_reader;
            logger.Info("Read {} SMV images of the sweep containing {}",
                        smv_reader.GetNumberOfImages(), input_file);
        } else if (input_is_xtc) {
            xtc_reader.ReadFiles(input_file);
            reader_ptr = &xtc_reader;
            logger.Info("Read {} XTC still images from {}", xtc_reader.GetNumberOfImages(), input_file);
        } else if (std::filesystem::is_directory(input_file)) {
            // A directory is never an HDF5 master, so handing it to the HDF5 reader only buries the
            // real answer - that no one-file-per-image sweep was found in it - under a page of HDF5
            // stack output.
            logger.Error("{} holds no CBF, marCCD, SMV or XTC data this program can read (a directory is "
                         "read as the sweep of frames it holds)", input_file);
            exit(EXIT_FAILURE);
        } else if (!broker_url.empty() && !std::filesystem::exists(input_file)) {
            // The collection is still being written: follow it from the broker.
            if (mode != RugnuxMode::MX) {
                logger.Error("Following a collection from the broker is for --mode mx only");
                exit(EXIT_FAILURE);
            }
            const char *token = std::getenv("JUNGFRAUJOCH_HTTP_TOKEN");
            if (token == nullptr) {
                logger.Error("{} does not exist yet, and following it from the broker needs the collection's token "
                             "in the environment variable JUNGFRAUJOCH_HTTP_TOKEN", input_file);
                exit(EXIT_FAILURE);
            }
            broker_feed = std::make_unique<BrokerFeed>(broker_url, token);
            // The broker's event stream starts with the start message: at once on a JUNGFRAU, when the
            // detector sends its own on a DECTRIS.
            const StartMessage start = broker_feed->WaitForStart();
            // The start message names the files relative to the collection's root; the path given here
            // has to be where its master file will be.
            const std::string master = std::filesystem::path(HDF5Metadata::MasterFileName(start)).generic_string();
            const std::string given = std::filesystem::path(input_file).lexically_normal().generic_string();
            if (given != master && !given.ends_with("/" + master)) {
                logger.Error("The broker at {} is writing {}, not {}", broker_feed->Host(), master, input_file);
                exit(EXIT_FAILURE);
            }
            if (!start.goniometer.has_value() || !start.goniometer->IsScanning()) {
                logger.Error("Following a collection from the broker is for rotation data, and {} is not", master);
                exit(EXIT_FAILURE);
            }
            live_reader.Open(start, input_file);
            broker_feed->Attach(live_reader);
            reader_ptr = &live_reader;
            logger.Info("Following collection {} (run {}) from the broker at {}: {} images in files of {}",
                        master, start.run_number, broker_feed->Host(), start.number_of_images, start.images_per_file);
            console->OnNote("still being written - following it from the broker");
        } else {
            hdf5_reader.ReadFile(input_file);
            reader_ptr = &hdf5_reader;
        }
    } catch (const std::exception &e) {
        logger.Error("Error reading input file: {}", e.what());
        exit(EXIT_FAILURE);
    }
    JFJochReader &reader = *reader_ptr;

    const auto dataset = reader.GetDataset();
    if (!dataset) {
        logger.Error("No experiment dataset found in the input file");
        exit(EXIT_FAILURE);
    }

    if (rotation_indexing_image_count <= 0) {
        logger.Error("Invalid number of rotation indexing images: {}", rotation_indexing_image_count);
        exit(EXIT_FAILURE);
    }

    logger.Info("Loaded dataset from {}", input_file);
    // Recorded in the reflection files.
    OutputProvenance output_provenance;
    output_provenance.command_line = provenance.command_line;
    DescribeInput(input_file, output_provenance);
    output_provenance.collection_date = dataset->arm_date;
    {
        // The header as the file states it, before anything is measured: what a question about a run
        // is answered from first.
        const auto &x = dataset->experiment;
        const auto gonio = x.GetGoniometer();
        const auto [direct_x, direct_y] = x.GetDiffractionGeometry().GetDirectBeam_pxl();
        logger.Info("Header: {} images, detector {} {} x {} px of {:.4f} mm, wavelength {:.5f} A, distance "
                    "{:.3f} mm, beam {:.2f} {:.2f} px (direct beam {:.2f} {:.2f}), tilt {:.4f} {:.4f} deg, {}, "
                    "polarization {}",
                    reader.GetNumberOfImages(), x.GetDetectorDescription(), x.GetXPixelsNum(), x.GetYPixelsNum(),
                    x.GetPixelSize_mm(), x.GetWavelength_A(), x.GetDetectorDistance_mm(), x.GetBeamX_pxl(),
                    x.GetBeamY_pxl(), direct_x, direct_y, x.GetPoniRot1_rad() * 180.0 / PI,
                    x.GetPoniRot2_rad() * 180.0 / PI,
                    gonio ? fmt::format("rotation from {:.3f} deg by {:.4f} deg per image", gonio->GetStart_deg(),
                                        gonio->GetIncrement_deg())
                          : std::string("no rotation axis"),
                    x.GetPolarizationFactor() ? fmt::format("{:.3f}", *x.GetPolarizationFactor())
                                              : std::string("not stated"));
        console->OnNote(fmt::format("{} images, {} {} x {} px", reader.GetNumberOfImages(),
                                    x.GetDetectorDescription(), x.GetXPixelsNum(), x.GetYPixelsNum()));
        console->OnNote(fmt::format("{:.4f} A, {:.1f} mm, {}", x.GetWavelength_A(), x.GetDetectorDistance_mm(),
                                    gonio ? fmt::format("{:.3f} deg per image", gonio->GetIncrement_deg())
                                          : std::string("no rotation axis")));
    }

    std::vector<MergedReflection> reference_data;
    bool reference_has_free_flags = false;
    const gemmi::SpaceGroup *reference_space_group = nullptr;
    std::optional<UnitCell> reference_cell;
    if (!ref_mtz.empty()) {
        try {
            const auto reference = LoadReferenceMtz(
                ref_mtz, ref_column.empty() ? std::nullopt : std::optional<std::string>(ref_column));
            reference_data = reference.reflections;
            reference_has_free_flags = reference.has_free_flags;

            logger.Info("Loaded {} reference reflections from {} ({}, column {}{}{})",
                        reference_data.size(), ref_mtz, reference.source, reference.used_column,
                        reference.squared ? ", squared to intensity" : "",
                        reference.default_column ? ", auto-selected" : ", user-specified");
            if (reference.has_free_flags)
                logger.Info("Reference carries R-free flags (column {}): {} of {} free; the merged "
                            "reflections will inherit this test set",
                            reference.free_column, reference.n_free, reference_data.size());
            if (reference.d_max > 0.0)
                logger.Info("Reference resolution range {:.2f} - {:.2f} A", reference.d_max, reference.d_min);
            if (reference.cell.has_value())
                logger.Info("Reference unit cell: a={:.3f} b={:.3f} c={:.3f} alpha={:.2f} beta={:.2f} gamma={:.2f}",
                            reference.cell->a, reference.cell->b, reference.cell->c,
                            reference.cell->alpha, reference.cell->beta, reference.cell->gamma);
            if (!reference.space_group_name.empty())
                logger.Info("Reference space group: {} (number {})",
                            reference.space_group_name, reference.space_group_number.value_or(0));

            // Check the reference against the cell that will actually drive the merge. --scale merges
            // in the cell stored in the input file (as the former jfjoch_scale did); the -C override
            // only takes effect on the full-analysis path, which otherwise determines its cell later by
            // indexing (unknown here, so nothing can be checked yet).
            const std::optional<UnitCell> data_cell =
                mode == RugnuxMode::Scale ? dataset->experiment.GetUnitCell() : fixed_reference_unit_cell;
            const auto warning = ReferenceConsistencyWarning(
                reference, data_cell,
                space_group != nullptr ? std::optional<int>(space_group->number) : std::nullopt);
            if (!warning.empty())
                logger.Warning("{}", warning);

            // A reference MTZ fixes the space group and unit cell, unless -S / -C override them.
            // (-S with the wrong enantiomorph, or -C with a different cell, is allowed - the explicit
            // flag always wins.) The cell is a soft reference: indexing may drift within tolerance.
            // The group in the setting the reference is written in, not only its number: its
            // intensities and free-R flags are indexed on those axes.
            if (!reference.space_group_xhm.empty())
                reference_space_group = gemmi::find_spacegroup_by_name(reference.space_group_xhm);
            reference_cell = reference.cell;
            // --mode scale re-merges reflections already indexed on the file's axes and cannot move
            // them, so there the reference names only the group; the full pipeline puts the merge into
            // the reference's frame (Rugnux.cpp) and takes its setting as well.
            if (space_group == nullptr && reference_space_group != nullptr) {
                space_group = mode == RugnuxMode::Scale
                                  ? gemmi::find_spacegroup_by_number(reference_space_group->number)
                                  : reference_space_group;
                logger.Info("Fixing space group from reference MTZ: {} ({})",
                            reference_space_group->xhm(), reference_space_group->number);
            }
            if (!fixed_reference_unit_cell.has_value() && reference.cell.has_value()) {
                fixed_reference_unit_cell = reference.cell;
                logger.Info("Fixing reference unit cell from reference MTZ (indexing may drift within tolerance)");
            }
        } catch (const std::exception &e) {
            logger.Error("Error reading reference {}: {}", ref_mtz, e.what());
            exit(EXIT_FAILURE);
        }
    }

    // --mode scale: re-scale and merge the already-integrated reflections stored in the input file,
    // without re-running spot finding or integration (folded in from the former rugnux_scale tool).
    if (mode == RugnuxMode::Scale) {
        // --mode scale re-merges reflections that are already integrated and already indexed; it runs
        // no space-group search and makes no P1 merge, so there is no ledger to print here. Said
        // out loud because this mode is the cheap CPU instrument someone calibrating the ledger will
        // reach for first, and silence would read as "the ledger found nothing".
        if (finalist_ledger_flag)
            logger.Warning("No finalist ledger: --mode scale re-merges an already-determined group and "
                           "runs no space-group search. Use --mode mx, which makes the P1 merge the "
                           "ledger is folded from.");
        // Re-scaling reads reflections a previous run integrated, which only a _process.h5 holds.
        if (input_is_cbf || input_is_marccd || input_is_smv || input_is_crystfel || input_is_xtc) {
            logger.Error("--mode scale needs the integrated reflections in a _process.h5; "
                         "a raw image sweep holds none. Run --mode mx on it first.");
            exit(EXIT_FAILURE);
        }
        const auto total_images = static_cast<int>(reader.GetNumberOfImages());
        const int last_image = (end_image < 0 || end_image >= total_images) ? total_images - 1 : end_image;
        auto reflections = hdf5_reader.ReadReflections(start_image, last_image);

        DiffractionExperiment experiment(dataset->experiment);
        configure_offline_output(experiment, output_prefix);
        // The reflections in the file are already indexed, so the cell and space group they were
        // integrated in are the file's to supply here - but an explicit -S / -C still wins.
        if (space_group != nullptr)
            experiment.SetSpaceGroup(*space_group);
        if (fixed_reference_unit_cell.has_value())
            experiment.SetUnitCell(fixed_reference_unit_cell);
        // A rotation (goniometer) dataset uses RotationScaleMerge unless --force-still asks for stills scaling.
        IndexingSettings indexing_settings;
        indexing_settings.RotationIndexing(experiment.GetGoniometer().has_value() && !force_still);

        // --detect-ice-rings, applied here as well as on the full path below: this block returns
        // before that one runs, so without it the flag is silently ignored by --scale. Same
        // precedence as there - command line, then the file, then the geometry's default.
        if (detect_ice_rings.has_value())
            experiment.DetectIceRings(detect_ice_rings.value());
        else if (!dataset->file_detect_ice_rings.has_value())
            experiment.DetectIceRings(indexing_settings.GetRotationIndexing());
        experiment.ImportIndexingSettings(indexing_settings);

        // Start from the same defaults the full pipeline uses, so --scale reproduces the merge that wrote
        // the _process.h5 rather than a weaker model of its own. Every CLI override below then applies on
        // top, exactly as in the full-analysis path.
        const bool rot = experiment.GetGoniometer().has_value() && !force_still;
        ScalingSettings scaling_settings = RugnuxDefaultScalingSettings(rot);
        if (d_min_scale_merge)
            scaling_settings.HighResolutionLimit_A(d_min_scale_merge.value());
        if (d_max_scale_merge)
            scaling_settings.LowResolutionLimit_A(*d_max_scale_merge > 0.0f
                                                  ? std::optional<double>(*d_max_scale_merge) : std::nullopt);
        if (resolution_cutoff_method) scaling_settings.ResolutionCutoff(*resolution_cutoff_method);
        if (resolution_cc_target) scaling_settings.ResolutionCCTarget(*resolution_cc_target);
        if (report_shell_count) scaling_settings.ReportShellCount(*report_shell_count);
        if (report_resolution_arg)
            scaling_settings.ReportResolutionRange_A(
                ParseReportResolution(*report_resolution_arg, scaling_settings, logger));
        // Rotation merges decide with Friedel mates merged, -A or not (see the Rugnux constructor).
        scaling_settings.MergeFriedel(!anomalous_mode || rot);
        scaling_settings.MinPartiality(min_partiality);
        scaling_settings.MinCapturedFraction(
            min_captured_fraction_arg.value_or(scaling_settings.GetMinCapturedFraction()));
        scaling_settings.CaptureUncertaintyCoeff(
            capture_uncertainty_arg.value_or(scaling_settings.GetCaptureUncertaintyCoeff()));
        scaling_settings.ForcedMosaicity(forced_mosaicity_arg);
        scaling_settings.MinCCForImage(min_image_cc / 100.0);   // --min-image-cc is percent; the setting is a fraction
        scaling_settings.StillsPartialityRefine(!simple_stills_flag);
        scaling_settings.ExpectedVarianceMerge(!no_expected_variance_merge);
        if (ice_min_score_arg)
            scaling_settings.IceMinScore(static_cast<float>(*ice_min_score_arg));
        if (ice_min_spot_ratio_arg)
            scaling_settings.IceMinSpotRatio(static_cast<float>(*ice_min_spot_ratio_arg));
        scaling_settings.OutlierRejectNsigma(
            outlier_reject_nsigma.value_or(scaling_settings.GetOutlierRejectNsigma()));
        scaling_settings.ScaleFulls(scale_fulls_arg.value_or(scaling_settings.GetScaleFulls()));
        scaling_settings.SmoothGDegrees(smooth_g_deg_arg.value_or(scaling_settings.GetSmoothGDegrees()));
        scaling_settings.RelativeBDegrees(relative_b_deg_arg.value_or(0.0));   // opt-in only; default off
        if (no_scaling_corrections)
            scaling_settings.CorrectionSurfaces(false);
        experiment.ImportScalingSettings(scaling_settings);

        if (!experiment.GetUnitCell()) {
            logger.Error("Experiment unit cell not found, cannot update reflection resolution");
            exit(EXIT_FAILURE);
        }
        // The stored reflections have to be in the setting of the cell they are about to be merged in,
        // or the merge's per-frame cell gate rejects every observation and the run dies far downstream
        // complaining about resolution shells. The reader has already applied /entry/MX/reindexMatrix,
        // so a file that carries one arrives consistent; one written before that dataset existed, by a
        // run whose space-group search re-seated the lattice after the images had gone to file, does
        // not - and the change of basis cannot be recovered from it, because the stored lattices carry
        // each frame's own goniometer rotation. Say so here, where both cells can be named, instead of
        // merging indices in a frame they do not belong to.
        {
            const UnitCell merge_cell = experiment.GetUnitCell().value();
            const float dist_tol = experiment.GetIndexingSettings().GetUnitCellDistTolerance();
            const float ang_tol = experiment.GetIndexingSettings().GetUnitCellAngleTolerance_deg();
            size_t n_indexed = 0, n_agree = 0;
            std::optional<UnitCell> file_cell;
            for (const auto &o : reflections)
                if (!o.reflections.empty()) {
                    ++n_indexed;
                    const auto cell = o.latt.GetUnitCell();
                    if (cell.is_close(merge_cell, dist_tol, ang_tol))
                        ++n_agree;
                    else if (!file_cell)
                        file_cell = cell;
                }
            if (n_indexed > 0 && n_agree == 0) {
                logger.Error("The per-image lattices stored in this file are not in the setting of the "
                             "cell it is being merged in, so no observation can be used. Merging in "
                             "a={:.3f} b={:.3f} c={:.3f} alpha={:.2f} beta={:.2f} gamma={:.2f}, but all "
                             "{} indexed images are in a={:.3f} b={:.3f} c={:.3f} alpha={:.2f} "
                             "beta={:.2f} gamma={:.2f}{}. Merge in the setting the file is in with "
                             "-S 1 -C {:.4f},{:.4f},{:.4f},{:.4f},{:.4f},{:.4f}, or reprocess the "
                             "images with --mode mx.",
                             merge_cell.a, merge_cell.b, merge_cell.c, merge_cell.alpha,
                             merge_cell.beta, merge_cell.gamma, n_indexed,
                             file_cell->a, file_cell->b, file_cell->c, file_cell->alpha,
                             file_cell->beta, file_cell->gamma,
                             dataset->reindex_matrix
                                 ? "" : " (the file carries no /entry/MX/reindexMatrix, so it was "
                                        "written before that was recorded)",
                             file_cell->a, file_cell->b, file_cell->c, file_cell->alpha,
                             file_cell->beta, file_cell->gamma);
                exit(EXIT_FAILURE);
            }
        }

        // The cell has to carry the group's own symmetry axes, not merely its centring. --mode scale
        // takes both from the file unless -S / -C override them, and an override that puts a 4-fold on
        // an axis the crystal does not have merges the data through operators that do not act on its
        // indices: measured, -S P41212 on a run indexed a=37.909 b=78.031 c=77.594 reported
        // COMPLETENESS= 195.3, since the possible-reflection count is then computed in one frame and
        // the observations in another. Nothing downstream can notice, so the check belongs here, with
        // both the cell and the group in hand.
        if (const auto merge_sg = experiment.GetGemmiSpaceGroup()) {
            const UnitCell uc = experiment.GetUnitCell().value();
            const double violation = MetricViolation(uc, *merge_sg);
            if (violation > MAX_METRIC_VIOLATION) {
                logger.Error("The space group {} cannot describe this cell: a={:.3f} b={:.3f} c={:.3f} "
                             "alpha={:.2f} beta={:.2f} gamma={:.2f} is not left invariant by the group's "
                             "own operators (metric violation {:.3f}, tolerance {:.3f}), so its symmetry "
                             "axes do not run along the axes the group puts them on. Merging would count "
                             "the possible reflections in one frame and the observed ones in another - a "
                             "completeness above 100% is the usual symptom. Merge in a group this cell "
                             "has, or reprocess the images with --mode mx.",
                             merge_sg->xhm(), uc.a, uc.b, uc.c, uc.alpha, uc.beta, uc.gamma,
                             violation, MAX_METRIC_VIOLATION);
                exit(EXIT_FAILURE);
            }
        }

        // Stills: a crystal indexed in a lattice containing the file's cell is put on that cell, as the full
        // pipeline does - before the resolution of every reflection is recomputed from the cell below,
        // which is right only for reflections indexed on it.
        if (!experiment.IsRotationIndexing()) {
            const auto relabel = RelabelOnSublattice(reflections, experiment.GetUnitCell().value(),
                                                     experiment.GetIndexingSettings());
            logger.Info("Put {} crystal(s) indexed in a lattice containing the file's cell on that cell",
                        relabel.frames);
        }
        auto refl_stats = UpdateReflectionResolution(experiment.GetUnitCell().value(), reflections);
        logger.Info("Read {} reflections from {} images", refl_stats.n_reflections, refl_stats.n_images);
        experiment.ImagesPerTrigger(refl_stats.n_images);

        // Ice-ring handling, as the full pipeline does it (Rugnux.cpp): flag reflections on a
        // hexagonal-ice powder ring so scaling skips them while the merge keeps them. The flag is not
        // stored per reflection, so it has to be recomputed here from the resolution just assigned -
        // otherwise --scale re-scales a dataset the writing run had scaled without those reflections,
        // and the per-image scales come out of a different fit than the ones in the file.
        const float ice_width = SpotFindingSettings().ice_ring_width_Q_recipA;
        // ...and gated the same way, on the per-image ice score the writing run stored in the file, so
        // --scale reaches the same verdict on the same data as the pipeline that produced it.
        double ice_sum = 0.0;
        size_t ice_n = 0;
        for (const float s : dataset->ice_ring_score)
            if (std::isfinite(s)) {
                ice_sum += s;
                ++ice_n;
            }
        const float ice_min_score = experiment.GetScalingSettings().GetIceMinScore();
        // ...and the spot channel, pooled over the run exactly as the full pipeline pools it.
        double ring_sum = 0.0, ctrl_sum = 0.0;
        for (const float v : dataset->spot_count_ice_rings)
            if (std::isfinite(v)) ring_sum += v;
        for (const float v : dataset->spot_count_ice_control)
            if (std::isfinite(v)) ctrl_sum += v;
        // Empty control + spots on the rings = the strongest ice evidence, not its absence.
        const double ice_spot_ratio = ctrl_sum > 0.0 ? ring_sum / ctrl_sum : (ring_sum > 0.0 ? 1.0e3 : 0.0);
        const float ice_min_spot_ratio = experiment.GetScalingSettings().GetIceMinSpotRatio();
        const bool ice_present = (ice_n == 0 || ice_sum / static_cast<double>(ice_n) >= ice_min_score)
            || (ice_min_spot_ratio > 0.0f && ice_spot_ratio >= ice_min_spot_ratio);
        if (experiment.IsDetectIceRings() && !ice_present) {
            logger.Info("Ice-ring handling: measured ice score {:.2f} and spot ratio {:.2f} below the "
                        "gates ({:.2f} / {:.2f}), no ice detected - ice-ring handling skipped entirely",
                        ice_sum / static_cast<double>(ice_n), ice_spot_ratio, ice_min_score,
                        ice_min_spot_ratio);
        } else if (experiment.IsDetectIceRings()) {
            size_t total = 0, flagged = 0;
            for (auto &outcome : reflections) {
                for (auto &r : outcome.reflections) {
                    ++total;
                    r.on_ice_ring = IsOnIceRing(r.d, ice_width);
                    if (r.on_ice_ring)
                        ++flagged;
                }
            }
            logger.Info("Ice-ring handling: flagged {} of {} reflections on ice rings (half-width {:.3f} A^-1); "
                        "excluded from scaling, kept for merging", flagged, total, ice_width);
        }

        console->OnStep("Scaling and merging");
        const auto scale_start = std::chrono::steady_clock::now();
        std::vector<MergedReflection> merged_reflections;
        std::vector<ScaledFull> scaled_fulls;   // the .hkl: rotation merges only
        MergeStatistics merged_statistics;
        double error_model_isa = 0.0;
        double error_model_isa_asymptotic = 0.0;
        bool error_model_isa_resolved = true;
        std::optional<double> resolution_fit_A;   // CC1/2 crossing, without the one-shell extension
        double error_model_a = 0.0;
        double error_model_b = 0.0;
        std::optional<MergeStatistics> reference_statistics;   // --report-resolution
        double reference_isa = 0.0;

        // Rotation (rot3d): the dedicated RotationScaleMerge does the whole self-scale -> 3D combine ->
        // merge, including the default-on decay + absorption correction surfaces. It does not support
        // external-reference scaling or wedge refinement.
        // Everything else (stills, reference scaling) uses ScaleOnTheFly + MergeOnTheFly.
        const bool is_rotation = experiment.IsRotationIndexing();
        if (is_rotation) {
            if (!reference_data.empty()
                || experiment.GetRefineRotationWedgeInScaling()
                || experiment.GetScalingSettings().GetRotationWedgeForScaling().has_value())
                throw JFJochException(JFJochExceptionCategory::InputParameterInvalid,
                                      "Rotation scaling/merging (RotationScaleMerge) does not support reference "
                                      "scaling or wedge refinement");
            // The stored reflections still hold a blank sweep end (the file is written image by image,
            // before anything is decided), so it is taken off here as the full pipeline takes it off.
            if (const auto [at_start, at_end] = TrimBlankSweepEnds(reflections, nthreads); at_start + at_end > 0)
                logger.Info("Sweep ends: left out {} frame(s) at the start and {} at the end that recorded "
                            "no diffraction", at_start, at_end);
            RotationScaleMerge rsm(experiment, reflections, experiment.GetUnitCell(),
                                   scaling_iter, nthreads, logger);
            rsm.Ingest();
            rsm.SetExportScaledFulls(!output_prefix.empty());
            // No pass to compare against here - --mode scale merges the stored reflections once - so
            // decline the extra merge the pre-correction CC1/2 would cost.
            auto r = rsm.Run(false, /*full_stats=*/true, /*measure_cc_before_corrections=*/false);
            merged_reflections = std::move(r.merged);
            merged_statistics = std::move(r.statistics);
            scaled_fulls = std::move(r.scaled_fulls);
            error_model_isa = r.isa;
            error_model_isa_asymptotic = r.isa_asymptotic;
            error_model_isa_resolved = r.isa_resolved;
            error_model_a = r.error_model_a;
            error_model_b = r.error_model_b;
            resolution_fit_A = r.resolution_fit_A;
            reference_statistics = std::move(r.reference_statistics);
            reference_isa = r.reference_isa;
        } else {
            // Scaling self-references: the reference MTZ (if any) fixes the cell/space group, reports
            // CCref and provides the R-free test set, but is NOT a scale anchor - scaling each image
            // against a foreign dataset injects cross-dataset systematics and is a worse reference than
            // the data's own merge. The per-image scale G is the exact one-pass solution, so one pass
            // (iterating a self-rebuilt reference only re-fits the freshly-scaled noise on weak stills).
            ScaleOnTheFly(experiment, MergeAll(experiment, reflections, nthreads, experiment.GetUnitCell())).Scale(reflections, nthreads);
            // Physical partiality post-refinement (default on; --simple-stills disables): refine a per-crystal
            // orientation tilt against the merge and recompute each reflection's partiality + scale correction
            // (no re-integration), then merge with the improved corrections.
            if (experiment.GetScalingSettings().GetStillsPartialityRefine()) {
                StillsPartialityRefine refiner(experiment);
                const double mean_tilt = refiner.Run(reflections, nthreads, experiment.GetUnitCell());
                logger.Info("Stills partiality post-refine: mean |dpsi| = {:.3f} deg", mean_tilt);
            }
            MergeOnTheFly merge_engine(experiment);
            merge_engine.Threads(nthreads);
            merge_engine.ReferenceCell(experiment.GetUnitCell());
            // --min-image-cc has to hold for the merge itself, not only for the reported statistics.
            merge_engine.FilterByImageCC(experiment.GetScalingSettings().GetMinCCForImage() > 0.0);
            // Fit the (a, b) error model from symmetry-mate scatter before merging, exactly as the full
            // pipeline does (Rugnux.cpp). Without this the offline --scale merge would use the identity
            // model and produce much worse stills intensities (no (b*I)^2 systematic term at all).
            merge_engine.RefineErrorModel(reflections);
            if (merge_engine.ErrorModelActive())
            {
                // XDS convention, so the pair reads directly against a CORRECT.LP; the stills ISa is
                // already the whole-range 1/b, there being no asymptote tier on this path.
                const auto em = ToXdsErrorModel(merge_engine.ErrorModelA(), merge_engine.ErrorModelB());
                logger.Info("Error model (XDS convention): a={:.3f} b={:.3e} ISa={:.1f} chi2={:.2f}",
                            em.a, em.b, em.isa, merge_engine.ErrorModelChi2());
            }
            merge_engine.AddImages(reflections);
            merged_reflections = merge_engine.ExportReflections();

            // Automatic high-resolution cutoff (post-merge), matching the full-analysis path: a manual
            // --scaling-high-resolution wins, otherwise trim the written reflections + reported shells
            // to the CC1/2 fall-off. (Rotation is cut inside RotationScaleMerge above.)
            const auto &cut_ss = experiment.GetScalingSettings();
            // The offline --scale path re-scales a stored _process.h5 and is never a P1 search merge.
            const std::optional<double> effective_d_min = ApplyResolutionCutoff(
                merged_reflections, cut_ss.GetHighResolutionLimit_A(), cut_ss.GetResolutionCutoff(),
                cut_ss.GetResolutionCCTarget(), /*for_search=*/false, logger, &resolution_fit_A);

            merged_statistics = merge_engine.MergeStats(merged_reflections, reflections, reference_data,
                                                        effective_d_min);
            if (const auto range = cut_ss.GetReportResolutionRange_A())
                reference_statistics = merge_engine.MergeStats(merged_reflections, reflections, reference_data,
                                                               std::nullopt, range);
            {   // stills: no asymptote tier, and its ISa already IS the whole-range 1/b
                const auto em = ToXdsErrorModel(merge_engine.ErrorModelA(), merge_engine.ErrorModelB());
                error_model_isa = em.isa;
                error_model_a = em.a;
                error_model_b = em.b;
            }
        }

        logger.Info("Scale + merge completed in {:.2f} s ({} unique reflections)",
                    std::chrono::duration<double>(std::chrono::steady_clock::now() - scale_start).count(),
                    merged_reflections.size());

        // Inherit the campaign's shared R-free test set from the reference MTZ (overriding the
        // per-hkl hash the merge assigned), so every dataset flags the same free reflections.
        // Only where the merge is recognisably the reference's crystal form on the reference's axes -
        // see the same step in Rugnux.cpp.
        if (reference_has_free_flags && !reference_data.empty() && !merged_reflections.empty()) {
            const auto match = MatchReference(merged_reflections, reference_data, experiment.GetSpaceGroupOrP1());
            if (match.cc >= MIN_REFERENCE_CC && match.matched_fraction >= MIN_REFERENCE_MATCHED_FRACTION) {
                const size_t matched = ApplyReferenceFreeFlags(merged_reflections, experiment.GetSpaceGroupOrP1(),
                                                              reference_data);
                logger.Info("R-free flags: inherited the reference test set ({} of {} merged reflections "
                            "matched; CC with the reference {:.3f})", matched, merged_reflections.size(), match.cc);
            } else
                logger.Warning("The reference MTZ does not match these data (CC {:.3f}, {:.0f}% of the merged "
                               "reflections in its range matched): its free-R flags were NOT inherited",
                               match.cc, 100.0 * match.matched_fraction);
        }

        // Dataset-wide Wilson B-factor estimate (like XDS's WILSON LINE B), as the full pipeline reports
        // it (Rugnux.cpp). Diagnostic only - it is not fed back into scaling; it lands in the printed
        // statistics, the mmCIF and the log. Without it --mode scale reports WILSON_B= nan.
        {
            const GlobalWilsonB wilson = CalcGlobalWilsonB(merged_reflections);
            merged_statistics.wilson_b = wilson.b;
            merged_statistics.wilson_b_correlation = wilson.correlation;
        merged_statistics.wilson_b_d_low_A = wilson.d_low_A;
        merged_statistics.wilson_b_d_high_A = wilson.d_high_A;
            if (std::isfinite(wilson.b) && wilson.b > 0.0)
                logger.Info("Wilson B-factor estimate: {:.2f} A^2 (correlation {:.3f}, {} shells, fitted over "
                            "{:.2f}-{:.2f} A)", wilson.b, wilson.correlation, wilson.n_shells, wilson.d_low_A,
                            wilson.d_high_A);
        }

        {
            std::ostringstream os;
            os << merged_statistics;
            logger.Info("Merging statistics:\n{}", os.str());
        }
        console->OnNote(fmt::format("{} unique reflections to {:.2f} A", merged_reflections.size(),
                                    merged_statistics.overall.d_min));
        console->OnStep("Analyses");

        // Space-group determination lives in the full rugnux pipeline; --scale only consumes a space
        // group (from the file or -S) and merges in it.
        const bool fixed_space_group = space_group || experiment.GetGemmiSpaceGroup().has_value();
        if (!fixed_space_group)
            logger.Warning("No space group in the input file or on the command line - merged in P1. "
                           "Re-run rugnux (which determines and stores the space group) or pass "
                           "-S to scale and merge in the correct symmetry.");

        const auto &twin_sg_opt = experiment.GetGemmiSpaceGroup();
        const gemmi::SpaceGroup *twin_sg = twin_sg_opt ? &*twin_sg_opt : nullptr;
        // Same order as the full pipeline: the pseudo-translation is measured first because the twin
        // verdict must know whether its own L-test was contaminated by one.
        TranslationalNCSResult tncs;
        if (const auto uc = experiment.GetUnitCell())
            tncs = AnalyzeTranslationalNCS(merged_reflections, gemmi::UnitCell(*uc), twin_sg);
        if (tncs.measurable)
            logger.Info("{}", TranslationalNCSToText(tncs));
        // Same as the full pipeline: without the reflections the lattice centring extinguishes. The
        // merged ASU of a centred group still holds keys in the absent class, and they are noise, not
        // intensities, in both statistics.
        const auto twin_uc = experiment.GetUnitCell();
        const std::optional<gemmi::UnitCell> twin_cell =
                twin_uc ? std::optional<gemmi::UnitCell>(*twin_uc) : std::nullopt;
        const auto twinning = AnalyzeTwinning(merged_reflections, twin_sg, 20,
                                              TranslationalNCSVectorForLTest(tncs),
                                              twin_sg ? twin_sg->centring_type() : 'P',
                                              twin_cell ? &*twin_cell : nullptr);
        logger.Info("{}", TwinningAnalysisToText(twinning));

        // Diffraction anisotropy, exactly as the full pipeline computes it (Rugnux.cpp) - no intensity
        // is corrected, the tensor is only the amplitudes' Wilson prior. The stored reflections have just been re-scaled above, so they carry
        // this merge's own per-image scale.
        if (experiment.GetUnitCell()) {
            AnisotropyRunInfo aniso_run;
            if (merged_statistics.sweep_quality.measured && merged_statistics.sweep_quality.sweep_deg > 0.0f)
                aniso_run.observed_rotation_deg = merged_statistics.sweep_quality.sweep_deg;
            aniso_run.dose_term_in_scale_model = experiment.GetScalingSettings().GetCorrectionSurfaces();
            aniso_run.radiation_damage_relative_b = merged_statistics.radiation_damage_delta_b;
            merged_statistics.anisotropy = AnalyzeAnisotropy(merged_reflections,
                                                             ScaledObservations(reflections, is_rotation, twin_sg,
                                                                                experiment.GetGoniometer()
                                                                                    ? experiment.GetGoniometer()->GetWedge_deg()
                                                                                    : 0.0f),
                                                             *experiment.GetUnitCell(), twin_sg, aniso_run);
            logger.Info("{}", AnisotropyToText(merged_statistics.anisotropy));
            // The amplitudes again with the anisotropic Wilson prior, as the full pipeline does.
            FrenchWilsonOptions fw_opts;
            fw_opts.num_threads = static_cast<int>(nthreads);
            fw_opts.anisotropy_hkl = AnisotropyTensorHKL(merged_statistics.anisotropy,
                                                         gemmi::UnitCell(*experiment.GetUnitCell()));
            ApplyFrenchWilson(merged_reflections, experiment.GetSpaceGroupOrP1(), fw_opts);
        }

        // Before the reflection files, as in the full pipeline: the model settles the enantiomorph and,
        // with no reference MTZ, the alternative indexing, and the files are written in what it settled.
        // A model that was asked for and could not be used has to reach the report, or the run ends
        // looking exactly like one that was never given --model.
        std::string model_validation_failure;
        std::optional<ModelValidationResult> model_validation;
        if (!output_prefix.empty() && model) {
            console->OnStep("Model validation");
            const auto data_sg = experiment.GetGemmiSpaceGroup();
            // With a reference MTZ the merohedral indexing was already resolved (stills per-image
            // scaling); only probe indexing by R-free when model-only, with no reference.
            // The merge's own shell bounds, so CC(model, data) is reported on the shells CC1/2 was.
            std::vector<float> report_shell_d_min;
            for (const auto &sh : merged_statistics.shells)
                report_shell_d_min.push_back(sh.d_min);
            auto validation =
                ValidateAgainstModel(merged_reflections, *experiment.GetUnitCell(), *model,
                                     logger,
                                     data_sg ? &*data_sg : nullptr,
                                     /*probe_indexing_ambiguity=*/reference_data.empty(),
                                     static_cast<size_t>(nthreads),
                                     experiment.GetWavelength_A(), report_shell_d_min);
            if (validation.maps)
                WriteModelMaps(*validation.maps, output_prefix, logger);
            validation.maps.reset();
            model_validation = validation;
            if (!validation.failure_reason.empty())
                model_validation_failure = validation.failure_reason;
            if (data_sg.has_value()) {
                const gemmi::SpaceGroup *adopted =
                    AdoptModelFrame(validation, merged_reflections, *data_sg,
                                    experiment.GetScalingSettings().GetMergeFriedel(), logger);
                if (adopted->number != data_sg->number)
                    experiment.SetSpaceGroup(*adopted);
                // The unmerged export below writes the integrated observations, so it follows the same
                // relabeling as the merged set - only the indexing moves a reflection; the enantiomorph
                // is a label - or the two files would describe different indexings of one dataset.
                // The cell moves with the indices too, for an indexing that is only a near-symmetry.
                const gemmi::Op &op = validation.indexing_op;
                if (!(op == gemmi::Op::identity())) {
                    for (auto &io : reflections)
                        for (auto &r : io.reflections) {
                            const gemmi::Op::Miller h = op.apply_to_hkl({{r.h, r.k, r.l}});
                            r.h = h[0]; r.k = h[1]; r.l = h[2];
                        }
                    experiment.SetUnitCell(CellInBasis(*experiment.GetUnitCell(), HklOperator(op)));
                }
            }
            // The coordinates that go with the maps just written, in the frame the reflection files
            // beside them carry. Written whenever the validation ran, not only where the rigid-body
            // step moved the model: it is also re-fractionalized into the data cell and may be
            // relabelled to the model's enantiomorph, so "did not move" is not "identical to the input
            // file". A rejected model is scored, placed and mapped like any other, and that is the case
            // where someone most wants to see the model in the density, so it gets its file too.
            if (validation.placed_model)
                WritePlacedModel(*validation.placed_model, *experiment.GetUnitCell(),
                                 experiment.GetSpaceGroupOrP1(), output_prefix, logger);
        }

        console->OnStep("Writing files");
        // Unmerged observations, from the integrated observations rather than the merged ones: the
        // partiality and the per-image scale are left for the reading program, which fits a scale
        // model of its own. Without an output prefix there is nowhere to put it, and the name would
        // come out as a bare "_unmerged.mtz".
        if (export_unmerged && !output_prefix.empty()) {
            const std::string path = output_prefix + "_unmerged.mtz";
            WriteUnmergedMtzReflections(reflections, *experiment.GetUnitCell(), experiment, true,
                                        output_provenance, path);
            logger.Info("Unmerged observations written to {}", path);
        }
        if (export_unmerged_partials && !output_prefix.empty()) {
            const std::string path = output_prefix + "_unmerged_partials.mtz";
            WriteUnmergedMtzReflections(reflections, *experiment.GetUnitCell(), experiment, false,
                                        output_provenance, path);
            logger.Info("Unmerged partials written to {}", path);
        }

        if (!output_prefix.empty()) {
            const ErrorModelReport em_report{
                    error_model_isa > 0 && error_model_isa_resolved
                            ? fmt::format("{:.2f}", error_model_isa) : "?",
                    error_model_isa_asymptotic > 0 && error_model_isa_resolved
                            ? fmt::format("{:.2f}", error_model_isa_asymptotic) : std::string(),
                    error_model_a > 0 ? fmt::format("{:.3f}", error_model_a) : std::string(),
                    error_model_b > 0 ? fmt::format("{:.4e}", error_model_b) : std::string()};
            WriteReflections(merged_reflections, *experiment.GetUnitCell(), experiment, merged_statistics,
                             em_report, twinning, output_provenance, output_prefix, static_cast<size_t>(nthreads),
                             &scaled_fulls);
        }

        // --mode scale re-merges stored reflections, so it determines a merging result and gets the
        // same report. It has no ProcessResult of its own; fill the parts that exist here.
        ProcessResult scale_result;
        scale_result.images_processed = reader.GetNumberOfImages();
        scale_result.consensus_cell = experiment.GetUnitCell();
        scale_result.space_group = experiment.GetGemmiSpaceGroup();
        scale_result.used_beam_x_pxl = experiment.GetBeamX_pxl();
        scale_result.used_beam_y_pxl = experiment.GetBeamY_pxl();
        scale_result.used_distance_mm = experiment.GetDetectorDistance_mm();
        // The tilt and the direct beam belong with them: the reader restores the poni rotations from
        // the input file's transformations chain, so they are known here. Left unset they stayed at
        // their zero-initialised default and the report asserted a FLAT detector on tilted data - a
        // measurement that was never made, in a block a user is invited to POST back to the
        // instrument. Same fill as the end of the per-image pass in Rugnux.cpp, from the same
        // experiment, so the four numbers describe ONE geometry.
        {
            const auto &g = experiment.GetDiffractionGeometry();
            constexpr double DEG = 180.0 / PI;
            scale_result.used_detector_tilt_deg = {g.GetPoniRot1_rad() * DEG, g.GetPoniRot2_rad() * DEG,
                                                   g.GetPoniRot3_rad() * DEG};
            const auto direct = g.GetDirectBeam_pxl();
            scale_result.used_direct_beam_x_pxl = direct.first;
            scale_result.used_direct_beam_y_pxl = direct.second;
        }
        scale_result.has_merge_statistics = true;
        scale_result.merge_statistics = merged_statistics;
        { std::ostringstream s; s << merged_statistics; scale_result.merge_statistics_text = s.str(); }
        scale_result.error_model_isa = error_model_isa;
        scale_result.error_model_isa_asymptotic = error_model_isa_asymptotic;
        scale_result.error_model_isa_resolved = error_model_isa_resolved;
        scale_result.error_model_a = error_model_a;
        scale_result.error_model_b = error_model_b;
        scale_result.resolution_fit_A = resolution_fit_A;
        scale_result.reference_merge_statistics = reference_statistics;
        scale_result.reference_isa = reference_isa;
        scale_result.has_reference = !reference_data.empty();
        scale_result.twinning = twinning;
        scale_result.model_validation = model_validation;
        if (!model_validation_failure.empty())
            scale_result.warnings.push_back({PathologyCode::MODEL_NOT_VALIDATED,
                                             "Model validation did not run: " + model_validation_failure});
        provenance.wall_time_s = std::chrono::duration<double>(
                std::chrono::steady_clock::now() - invocation_start).count();
        logger.Info("Total wall time: {:.2f} s", provenance.wall_time_s);
        const ReportDocument doc = WriteResultReport(output_prefix, input_file, experiment, scale_result, logger,
                                                     provenance);
        console->Finish();
        PrintSummary(*console, doc, output_prefix, files_since, provenance.wall_time_s);
        return 0;
    }

    uint64_t total_images_in_file = reader.GetNumberOfImages();
    if (end_image < 0 || end_image > total_images_in_file)
        end_image = total_images_in_file;

    if (image_stride < 0) {
        logger.Error("Image stride cannot be negative");
        exit(EXIT_FAILURE);
    }

    if (image_stride == 0) {
        logger.Error("Image stride cannot be zero");
        exit(EXIT_FAILURE);
    }

    // Round UP: the worker loop walks ordinals until start + ordinal * stride reaches end_image, so a
    // stride that does not divide the range evenly still processes a final partial step. Rounding down
    // here would size the per-image arrays one short of the ordinals that index them.
    int images_to_process = (end_image - start_image + image_stride - 1) / image_stride;

    if (images_to_process <= 0) {
        logger.Warning("No images to process (Start: {}, End: {} Stride: {}, Total: {})", start_image, end_image,
            image_stride, total_images_in_file);
        return 0;
    }

    // 2. Setup Experiment & Components
    DiffractionExperiment experiment(dataset->experiment);

    // Geometry overrides (default: keep the value stored in the input file). Applied before the
    // azimuthal-integration settings are derived, which depend on the geometry.
    if (beam_x) experiment.BeamX_pxl(beam_x.value());
    if (beam_y) experiment.BeamY_pxl(beam_y.value());
    if (detector_distance_mm) experiment.DetectorDistance_mm(detector_distance_mm.value());
    if (wavelength_A) experiment.IncidentEnergy_keV(WVL_1A_IN_KEV / wavelength_A.value());
    if (rot1_rad) experiment.PoniRot1_rad(rot1_rad.value());
    if (rot2_rad) experiment.PoniRot2_rad(rot2_rad.value());
    if (rot3_rad) experiment.PoniRot3_rad(rot3_rad.value());
    // The discrete part of the detector orientation, which the file does not state for a detector this
    // system did not assemble. Never derived from rot3 - it says how the image is stored, and a fitted
    // angle must not change that.
    if (detector_mirror_y || detector_quarter_turns != 0)
        experiment.Detector().ImageOrientation(
                DetectorOrientation(detector_mirror_y, detector_quarter_turns));
    // --polarization is applied after configure_offline_output below, which sets the rugnux default.

    // Calibrating from the run-summed profile needs the profile to be binned in azimuth - see
    // CALIBRATION_AZIM_BINS_DEFAULT. An explicit --azim-phi-bins always wins.
    if (mode == RugnuxMode::Calibration && calibration_method == CalibrationMethod::Rings
        && !azimuthal_bins.has_value())
        azimuthal_bins = CALIBRATION_AZIM_BINS_DEFAULT;

    // Azimuthal integration (default q-spacing 0.01 1/A, from AzimuthalIntegrationSettings): the profile
    // resolves the narrow ice rings for the ice-ring score. Shared by every mode that reads images.
    // -q / --azim-* / correction flags override; defaults come from the input file.
    {
        AzimuthalIntegrationSettings azint_settings = experiment.GetAzimuthalIntegrationSettings();
        if (min_q || max_q)
            azint_settings.QRange_recipA(min_q.value_or(azint_settings.GetLowQ_recipA()),
                                         max_q ? max_q : azint_settings.GetRequestedHighQ_recipA());
        if (q_spacing)
            azint_settings.QSpacing_recipA(q_spacing.value());
        if (azimuthal_bins)
            azint_settings.AzimuthalBinCount(azimuthal_bins.value());
        if (polarization_correction)
            azint_settings.PolarizationCorrection(polarization_correction.value());
        if (solid_angle_correction)
            azint_settings.SolidAngleCorrection(solid_angle_correction.value());
        experiment.ImportAzimuthalIntegrationSettings(azint_settings);
        logger.Info("Azimuthal integration: Q [{:.4f}, {:.4f}] 1/A, spacing {:.4f}, {} Q x {} azimuthal bins",
                    azint_settings.GetLowQ_recipA(), azint_settings.GetHighQ_recipA(),
                    azint_settings.GetQSpacing_recipA(), azint_settings.GetQBinCount(),
                    azint_settings.GetAzimuthalBinCount());
    }

    // --mode azint: azimuthal integration only (no spot finding / indexing / scaling). Rugnux reads
    // the geometry and azimuthal-integration settings configured above off the experiment.
    if (mode == RugnuxMode::Azint) {
        // As for --mode calibration below: the polarization factor is a rugnux analysis default and it
        // scales the profile this mode exists to produce, so apply the defaults and then let an explicit
        // --polarization override them. Without this the flag was parsed and then dropped on this path.
        ApplyRugnuxExperimentDefaults(experiment);
        if (polarization_factor) experiment.PolarizationFactor(polarization_factor.value());

        ProcessConfig config;
        config.mode = ProcessMode::AzimuthalIntegration;
        config.start_image = start_image;
        config.end_image = end_image;
        config.stride = image_stride;
        config.nthreads = nthreads;
    config.nthreads_auto = nthreads_auto;
        config.detect_beam_stop = detect_beam_stop;
        config.beam_center_check = beam_center_check;
        // The profiles go to <prefix>_process.h5, the output of this mode.
        std::optional<ProcessFileSink> sink;
        if (!output_prefix.empty())
            config.image_sink = &sink.emplace(output_prefix);

        Rugnux process(reader, experiment, *dataset->pixel_mask, config);
        g_active_process = &process;
        std::signal(SIGINT, handle_sigint);

        ProcessResult result;
        try {
            result = process.Run(console.get());
        } catch (const std::exception &e) {
            logger.Error("Processing failed: {}", FailureText(e));
            exit(EXIT_FAILURE);
        }
        g_active_process = nullptr;

        logger.Info("Processing time: {:.2f} s, frame rate {:.2f} Hz, throughput {:.2f} MB/s",
                    result.total_time_s, result.frame_rate_hz, result.throughput_MBs);
        if (result.cancelled)
            logger.Warning("Processing was cancelled after {} images", result.images_processed);
        console->Finish();
        console->Rule('=');
        PrintClosing(*console, output_prefix, files_since, console->Elapsed());
        return 0;
    }

    // --mode calibration: fit the detector geometry to the calibrant's powder rings, measured over
    // every selected image, and write it as a PONI file.
    if (mode == RugnuxMode::Calibration) {
        // The same analysis defaults every other mode gets (configure_offline_output applies them for
        // the MX path further down). The polarization factor is one of them and it enters the summed
        // azimuthal profile the rings are measured in, so without this the CLI and the viewer's
        // "Analyze dataset", which always applies them, would fit slightly different ring positions.
        ApplyRugnuxExperimentDefaults(experiment);
        if (polarization_factor) experiment.PolarizationFactor(polarization_factor.value());

        ProcessConfig config;
        config.mode = ProcessMode::Calibration;
        config.calibration_method = calibration_method;
        config.calibration_refine_tilt = calibration_refine_tilt;
        // -C wins over --calibrant: a cell given on the command line IS the standard, and the built-in
        // table is only the convenience for the five that have names. -S, where it is given, supplies
        // the absences - without it the cell is taken as primitive, which for a centred standard would
        // open the ring list with a reflection that is not there and scale the whole calibration.
        std::string calibrant_label = calibrant;
        if (fixed_reference_unit_cell.has_value()) {
            config.calibrant_ring_q = space_group != nullptr
                    ? CalculateXtalRings(*fixed_reference_unit_cell, *space_group)
                    : CalculateXtalRings(*fixed_reference_unit_cell);
            calibrant_label = fmt::format("cell {:.4f},{:.4f},{:.4f},{:.3f},{:.3f},{:.3f} ({})",
                                          fixed_reference_unit_cell->a, fixed_reference_unit_cell->b,
                                          fixed_reference_unit_cell->c, fixed_reference_unit_cell->alpha,
                                          fixed_reference_unit_cell->beta, fixed_reference_unit_cell->gamma,
                                          space_group != nullptr ? space_group->hm : "assumed primitive");
            if (config.calibrant_ring_q.empty()) {
                logger.Error("The unit cell given with -C produces no rings");
                return 1;
            }
        } else {
            config.calibrant_ring_q = CalibrantRings(calibrant);
        }
        config.start_image = start_image;
        config.end_image = end_image;
        config.stride = image_stride;
        config.nthreads = nthreads;
    config.nthreads_auto = nthreads_auto;
        config.detect_beam_stop = detect_beam_stop;
        config.beam_center_check = beam_center_check;
        // No image sink: the .poni below is the output of this mode.

        // Ice-ring handling has no place in a calibration run and does active harm. Flagged spots are
        // sorted LAST by the spot budget (FilterSpotsByCount), so they are the first thrown away - which
        // for --calibrant ice discards exactly the spots being calibrated on, and for every other
        // standard discards whichever of its rings happen to fall in the fixed hexagonal bands.
        experiment.DetectIceRings(false);

        // Spot finding for --calibration spots. Indexing is off: a calibration wants the spot positions
        // and nothing else, and the calibrant is a powder with no lattice to index.
        config.spot_finding.enable = true;
        config.spot_finding.indexing = false;
        config.spot_finding.signal_to_noise_threshold = sigma_spot_finding;
        config.spot_finding.photon_count_threshold = photon_count_threshold_spot_finding;
        config.spot_finding.min_pix_per_spot = min_pix_per_spot.value_or(2);
        config.spot_finding.adaptive_threshold = adaptive_spots.value_or(true);
        config.spot_finding.high_resolution_limit = d_min_spot_finding;
        config.spot_finding.false_pixels_per_frame = false_pixels_per_frame;
        config.spot_finding.low_resolution_limit = d_max_spot_finding;
        experiment.MaxSpotCount(max_spot_count_override.value_or(RUGNUX_MAX_SPOT_COUNT));

        logger.Info("Powder calibration: calibrant {} ({} rings), method {}, {} azimuthal bins, tilt {}",
                    calibrant_label, config.calibrant_ring_q.size(),
                    calibration_method == CalibrationMethod::Rings ? "rings" : "spots",
                    experiment.GetAzimuthalIntegrationSettings().GetAzimuthalBinCount(),
                    calibration_refine_tilt ? "refined" : "fixed");

        Rugnux process(reader, experiment, *dataset->pixel_mask, config);
        g_active_process = &process;
        std::signal(SIGINT, handle_sigint);

        ProcessResult result;
        try {
            result = process.Run(console.get());
        } catch (const std::exception &e) {
            logger.Error("Calibration failed: {}", FailureText(e));
            return 1;
        }
        g_active_process = nullptr;

        if (!result.calibration.has_value()) {
            logger.Error("Calibration produced no geometry");
            return 1;
        }
        const auto &cal = *result.calibration;
        const auto &g = cal.geometry;
        const DiffractionGeometry header = experiment.GetDiffractionGeometry();
        const float pxl_mm = g.GetPixelSize_mm();
        constexpr double RAD_TO_DEG = 180.0 / PI;

        // The calibration is its own summary: the geometry, what it is worth, and the verdict.
        console->Finish();
        console->Rule('=');
        const auto cal_line = [&](const std::string &text) {
            console->Line(" " + text);
            logger.Info("{}", text);
        };
        cal_line(fmt::format("Calibration:     {} ring points, rms {:.3f} px "
                             "(beam centre sigma {:.3f} px)",
                             cal.ring_points, cal.rms_radial_pxl, cal.beam_sigma_pxl));
        // What the rings said the distance was before the fit ran. The fit only converges from a few
        // per cent out, so this is what decides whether the run had a chance at all - and a large gap
        // from the header is the answer to the question the calibration was run to ask.
        if (cal.seed_distance_mm > 0.0f)
            cal_line(fmt::format("Ring seed:       distance {:.4f} mm from the rings themselves "
                                 "({:+.4f} mm from the header)",
                                 cal.seed_distance_mm,
                                 cal.seed_distance_mm - cal.header_distance_mm));
        else
            cal_line("Ring seed:       not measurable - the profile shows fewer than two rings");

        cal_line(fmt::format("PONI x:          {:.3f} px = {:.4f} mm  ({:+.3f} px from the header)",
                             g.GetBeamX_pxl(), g.GetBeamX_pxl() * pxl_mm,
                             g.GetBeamX_pxl() - header.GetBeamX_pxl()));
        cal_line(fmt::format("PONI y:          {:.3f} px = {:.4f} mm  ({:+.3f} px from the header)",
                             g.GetBeamY_pxl(), g.GetBeamY_pxl() * pxl_mm,
                             g.GetBeamY_pxl() - header.GetBeamY_pxl()));
        cal_line(fmt::format("Rot1:            {:+.6f} rad = {:+.4f} deg  ({:+.6f} rad from the header)",
                             g.GetPoniRot1_rad(), g.GetPoniRot1_rad() * RAD_TO_DEG,
                             g.GetPoniRot1_rad() - header.GetPoniRot1_rad()));
        cal_line(fmt::format("Rot2:            {:+.6f} rad = {:+.4f} deg  ({:+.6f} rad from the header)",
                             g.GetPoniRot2_rad(), g.GetPoniRot2_rad() * RAD_TO_DEG,
                             g.GetPoniRot2_rad() - header.GetPoniRot2_rad()));
        cal_line(fmt::format("Distance:        {:.4f} mm  ({:+.4f} mm from the header)",
                             g.GetDetectorDistance_mm(),
                             g.GetDetectorDistance_mm() - header.GetDetectorDistance_mm()));
        // The PONI is the point of normal incidence, which is what the .poni file wants; the direct beam
        // is where the beam actually lands, which is the number every other program reports as the beam
        // centre. They part company by distance*tan(rot) as soon as the detector is tilted, so print both.
        const auto [beam_x, beam_y] = g.GetDirectBeam_pxl();
        cal_line(fmt::format("Direct beam:     {:.3f}, {:.3f} px", beam_x, beam_y));

        // Where the spots put the beam, independently of everything above. The circle through them
        // reads nothing from the header, so it holds in exactly the regime the summed profile does not:
        // a profile binned about a badly wrong centre shows each ring smeared across its sectors, and no
        // amount of seeding recovers that - the fit then converges, prettily, on the wrong geometry.
        // Printed as a fact rather than gated on, because the reader can see at a glance whether two
        // methods that share no assumption agree.
        if (cal.spots_geometry)
            cal_line(fmt::format("Spot cross-check: the circle through the spots puts the beam at "
                                 "{:.1f}, {:.1f} px - {:.1f} px from the fitted centre",
                                 cal.spots_geometry->GetBeamX_pxl(),
                                 cal.spots_geometry->GetBeamY_pxl(),
                                 cal.spots_disagreement_pxl));

        // What the fit says about itself. The scatter line above is about the MEASUREMENTS; this is
        // about the PARAMETERS, and the two disagree exactly where the calibration is worth doubting:
        // a fit with few rings can sit tightly on the points it has while leaving the tilt free to
        // trade tens of pixels of beam centre for itself. The correlations name that trade - rot1
        // against the beam in x, rot2 against y - and approach 1 as the two stop being separable.
        if (const auto &u = cal.uncertainty; u.valid) {
            cal_line(fmt::format("Fit sigma:       PONI {:.3f}, {:.3f} px   distance {:.4f} mm",
                                 u.sigma_beam_x_pxl, u.sigma_beam_y_pxl, u.sigma_distance_mm));
            if (u.sigma_rot1_rad > 0.0 || u.sigma_rot2_rad > 0.0)
                cal_line(fmt::format("                 rot1 {:.4f} deg, rot2 {:.4f} deg   "
                                     "correlation with PONI {:+.3f} / {:+.3f}",
                                     u.sigma_rot1_rad * RAD_TO_DEG, u.sigma_rot2_rad * RAD_TO_DEG,
                                     u.corr_beam_x_rot1, u.corr_beam_y_rot2));
            else
                cal_line("                 tilt held fixed");
        } else {
            cal_line("Fit sigma:       not available - the fit is degenerate at its solution");
        }
        // Whether the tilt is a measurement or an artefact of a fit that could not tell it from the beam
        // centre. Reported either way: a declined tilt changes what the PONI means, and a kept one is
        // not a certified one - the estimator is limited by systematics rather than by this sigma.
        if (!calibration_refine_tilt) {
            cal_line("Tilt:            held at the header value (--no-refine-tilt)");
        } else if (cal.tilt_refined) {
            cal_line(fmt::format("Tilt:            refined; it stands {:.1f}x its own sigma",
                                 cal.tilt_significance));
        } else if (cal.tilt_significance > 0.0f) {
            cal_line(fmt::format("Tilt:            DECLINED and pinned - it came out at only "
                                 "{:.1f}x its own sigma, which is not a measurement of a tilt but "
                                 "of a shift of the beam centre", cal.tilt_significance));
        } else {
            // Distinct from the case above and worth saying so: there, the tilt was measured and found
            // too small to believe; here the fit could not measure it at all, because the rings it had
            // do not separate a tilt from a beam-centre shift in the first place.
            cal_line("Tilt:            DECLINED and pinned - these rings cannot separate a tilt "
                     "from a shift of the beam centre at all");
        }

        // Whether any of the above is a measurement. A calibration that hands back a number out of the
        // input file looks exactly like one that measured it - the same residual, the same sigmas, the
        // same four decimal places - so it has to be said outright.
        if (!cal.converged)
            cal_line("Verdict:         NOT A CALIBRATION - " + cal.reason);

        const std::string poni_path = output_prefix + ".poni";
        const std::string json_path = output_prefix + ".json";
        try {
            // The JSON FIRST, and ahead of anything the poni can refuse. It is the file that can state everything -
            // the verdict, the uncertainty, and a geometry a PONI has no fields for - so it must exist
            // even where the poni cannot be written, and it is wanted most exactly when the fit failed.
            // WritePoniFile refuses a detector whose image orientation a PONI cannot express; refusing
            // by throwing would otherwise take the JSON with it and leave a run whose own error text
            // says "the .json beside it carries the full geometry" beside no .json at all.
            WriteCalibrationJson(json_path, experiment, cal, calibrant_label,
                                 calibration_method == CalibrationMethod::Rings ? "rings" : "spots");
            // A .poni file states where the detector is and nothing else. It has no field for doubt, so
            // there is no honest way to write a geometry that is not a measurement into one - every
            // program that reads it downstream would read it as if it were.
            if (cal.converged)
                WritePoniFile(poni_path, experiment, g);
        } catch (const std::exception &e) {
            logger.Error("{}", e.what());
            return 1;
        }
        if (!cal.converged) {
            // Non-zero as well, because the caller this protects is a script, and a script reads the
            // exit code and not the ring statistics.
            logger.Error("Calibration did not converge: {}. Wrote {} with converged false; no {} was "
                         "written, because a PONI file cannot say that", cal.reason, json_path,
                         poni_path);
            return 1;
        }
        logger.Info("Wrote {} and {}", poni_path, json_path);
        console->Rule('-');
        PrintClosing(*console, output_prefix, files_since, console->Elapsed());
        return 0;
    }

    configure_offline_output(experiment, output_prefix);
    // 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());
    ClearStoredCrystal(experiment);            // shared with the viewer; -S / -C below override it
    if (space_group != nullptr)
        experiment.SetSpaceGroup(*space_group);
    experiment.ImagesPerTrigger(images_to_process);

    // Re-determine the unit cell from scratch: discard any cell stored in the input file so
    // indexing is not biased by it. A stale or wrong stored cell otherwise resolves the indexing
    // algorithm to FFBIDX and drives it to the wrong lattice (e.g. a non-cubic cell for a cubic
    // crystal). A user-supplied -C cell still takes effect (clears to nullopt when absent).
    experiment.SetUnitCell(fixed_reference_unit_cell);

    // --refine-geometry defaults ON for stills whenever a reference cell is available (-C or a
    // reference MTZ): that is exactly when the geometry bundle-adjust can act (it anchors on a known
    // cell) and where it helps weak/sparse stills. It is a no-op for rotation (which has its own
    // two-pass) and for de-novo stills (no cell yet), so auto-enabling it only where it does something
    // avoids spurious "skipping" warnings. Explicit --refine-geometry[=N] still forces it on;
    // --refine-geometry=off opts out.
    if (!refine_geometry.has_value() && !refine_geometry_disabled) {
        const bool is_stills = force_still || !RugnuxRotationData(experiment);
        if (is_stills && experiment.GetUnitCell().has_value())
            refine_geometry = RUGNUX_REFINE_GEOMETRY_FRAMES;
    }

    experiment.MaxSpotCount(max_spot_count_override.value_or(RUGNUX_MAX_SPOT_COUNT));
    if (max_spot_count_override.has_value())
        logger.Info("Max spot count overridden to {}", max_spot_count_override.value());

    // X-ray bandwidth: CLI overrides the value carried in the dataset; otherwise
    // keep whatever the dataset provided (0 / none -> monochromatic).
    if (bandwidth_fwhm)
        experiment.BandwidthFWHM(bandwidth_fwhm);
    if (experiment.GetBandwidthFWHM())
        logger.Info("X-ray bandwidth FWHM set to {:.4f}", experiment.GetBandwidthFWHM().value());

    // Rotation vs stills. A dataset collected on a rotation goniometer is processed as rotation data
    // (two-pass indexing) by default; --force-still forces per-frame stills. The rotation flags
    // (-R / --single-pass-rotation / --force-rotation-lattice) still request rotation explicitly and
    // choose the pass/lattice; at this point they show up as rotation_indexing already being set.
    // A stationary axis is stills (RugnuxRotationData).
    const bool has_goniometer = RugnuxRotationData(experiment);
    if (force_still) {
        if (rotation_indexing) {
            logger.Error("--force-still conflicts with -R / --single-pass-rotation / --force-rotation-lattice");
            exit(EXIT_FAILURE);
        }
        if (has_goniometer)
            logger.Info("--force-still: treating the rotation dataset as independent stills");
    } else if (!rotation_indexing && has_goniometer) {
        rotation_indexing = true;
        two_pass_rotation = true;
        logger.Info("Dataset has a rotation goniometer axis: processing as rotation data (two-pass "
                    "indexing). Use --force-still to treat it as stills.");
    }

    // A stride cuts every rocking curve. The angles still come out right - the goniometer is shifted so
    // one ordinal is one stride - but a reflection's partials are then sampled every k-th frame, so the
    // combine sees a fraction of each event, the captured fraction collapses, and the partiality divides
    // by a width the sweep never delivered. There is no reading of a strided rotation sweep worth having,
    // so it is refused rather than processed into a plausible wrong answer.
    if (rotation_indexing && image_stride != 1) {
        logger.Error("-t/--stride {} cannot be used on rotation data: skipping frames cuts every "
                     "reflection's rocking curve, so the combined fulls and their partiality would be "
                     "measured over frames the sweep never recorded. Process the sweep whole, or select "
                     "a contiguous range with -s/-e. --mode azint and --force-still still take a stride.",
                     image_stride);
        exit(EXIT_FAILURE);
    }

    // Scaling and merging are on by default (run_scaling initialised true); --no-merge turns them off
    // for both rotation and stills, in which case only the per-image _process.h5 is written.

    // The finalist ledger is folded from a P1 merge, so a run that does no merging has
    // none to fold. Said here, where the flag that decided it is in hand: the pipeline's own decline
    // message sits inside the scaling block and is unreachable once that block is switched off, and
    // silence would read as "the ledger found nothing to report" rather than "it never ran".
    if (finalist_ledger_flag && !run_scaling)
        logger.Warning("No finalist ledger: --no-merge skips scaling and merging, and the ledger is "
                       "folded from a P1 merge. Drop --no-merge to get one.");

    // Configure Indexing
    IndexingSettings indexing_settings;
    indexing_settings.Algorithm(indexing_algorithm);
    if (min_indexed_spots) indexing_settings.ViableCellMinSpots(min_indexed_spots.value());
    indexing_settings.RotationIndexing(rotation_indexing);
    if (rotation_indexing_range.has_value())
        indexing_settings.RotationIndexingMinAngularRange_deg(rotation_indexing_range.value());
    indexing_settings.GeomRefinementAlgorithm(refinement_algorithm);
    indexing_settings.IndexIceRings(index_ice_rings);
    if (fft_min_unit_cell_A) indexing_settings.FFT_MinUnitCell_A(fft_min_unit_cell_A.value());
    experiment.ImportIndexingSettings(indexing_settings);

    // --detect-ice-rings[=on|off] overrides the value carried in from the dataset (HDF5MetadataSource
    // sets DetectIceRings from the master file's detect_ice_rings key); with no flag the dataset stands.
    // Where the file says nothing at all, the default is the geometry's: on for rotation, off for
    // stills. A rotation sweep sits on the same rings for the whole run, so ice there is a coherent
    // systematic worth handling, and the ice-presence gate keeps it inert on a clean crystal; a serial
    // stills run has too few spots per image to spend any of them on flagging.
    experiment.DetectIceRings(detect_ice_rings.value_or(
            RugnuxDetectIceRings(dataset->file_detect_ice_rings, rotation_indexing)));

    // Scale-fulls refits the per-frame scale on the rotation combined fulls; on by default for rotation
    // data (where it lifts ISa substantially) and off for stills. --no-scale-fulls overrides.
    const bool scale_fulls = scale_fulls_arg.value_or(rotation_indexing);

    ScalingSettings scaling_settings = RugnuxDefaultScalingSettings(rotation_indexing);
    scaling_settings.ScaleFulls(scale_fulls);
    scaling_settings.SmoothGDegrees(smooth_g_deg_arg.value_or(scaling_settings.GetSmoothGDegrees()));
    scaling_settings.RelativeBDegrees(relative_b_deg_arg.value_or(0.0));   // opt-in only; default off
    if (no_scaling_corrections)
        scaling_settings.CorrectionSurfaces(false);
    scaling_settings.StillsPartialityRefine(!simple_stills_flag);
    scaling_settings.ExpectedVarianceMerge(!no_expected_variance_merge);
    if (ice_min_score_arg)
        scaling_settings.IceMinScore(static_cast<float>(*ice_min_score_arg));
    if (ice_min_spot_ratio_arg)
        scaling_settings.IceMinSpotRatio(static_cast<float>(*ice_min_spot_ratio_arg));
    if (d_min_scale_merge)
        scaling_settings.HighResolutionLimit_A(d_min_scale_merge.value());
    if (d_max_scale_merge)
        scaling_settings.LowResolutionLimit_A(*d_max_scale_merge > 0.0f
                                              ? std::optional<double>(*d_max_scale_merge) : std::nullopt);
    if (resolution_cutoff_method) scaling_settings.ResolutionCutoff(*resolution_cutoff_method);
    if (resolution_cc_target) scaling_settings.ResolutionCCTarget(*resolution_cc_target);
    if (report_shell_count) scaling_settings.ReportShellCount(*report_shell_count);
    if (report_resolution_arg)
        scaling_settings.ReportResolutionRange_A(
            ParseReportResolution(*report_resolution_arg, scaling_settings, logger));
    scaling_settings.MergeFriedel(!anomalous_mode);
    scaling_settings.MinPartiality(min_partiality);
    // Drop edge-of-sweep truncated fulls (rocking curve captured < this fraction) from the rot3d combine.
    // Defaults ON (0.7) for rotation - removes the low-capture fulls that inflate low-res R-meas and
    // slightly bias accuracy; off for non-rot3d (no combine). 0.7 (rather than 0.5) also strips the
    // partiality-extrapolated fulls that dominate the intensity second moment on weakly-diffracting
    // crystals, so the de-novo space-group search is no longer starved by the error-model I/sigma floor
    // (e.g. a weakly-diffracting F-cubic or hexagonal crystal recovers its true space group instead of
    // P1). An explicit --min-captured-fraction wins.
    scaling_settings.MinCapturedFraction(min_captured_fraction_arg.value_or(scaling_settings.GetMinCapturedFraction()));
    // Capture-aware systematic sigma defaults ON (1.0) for the rot3d combine - it down-weights the
    // over-extrapolated under-captured fulls and, with the mosaicity fix, lifts rotation ISa/anomalous
    // substantially. Off for non-rot3d (no combine). An explicit --capture-uncertainty always wins.
    scaling_settings.CaptureUncertaintyCoeff(capture_uncertainty_arg.value_or(scaling_settings.GetCaptureUncertaintyCoeff()));
    scaling_settings.ForcedMosaicity(forced_mosaicity_arg);
    scaling_settings.MinCCForImage(min_image_cc / 100.0);   // --min-image-cc is in percent; the setting is a fraction
    // Rotation default: run the de-novo space-group search a second time on a merge of only the
    // well-measured observations and keep whichever found more symmetry. It cannot lose symmetry - see
    // Rugnux.cpp - so the cut being imperfect only means the second opinion contributes nothing.
    scaling_settings.SearchMinZeta(search_min_zeta_arg.value_or(scaling_settings.GetSearchMinZeta()));
    scaling_settings.OutlierRejectNsigma(
        outlier_reject_nsigma.value_or(scaling_settings.GetOutlierRejectNsigma()));

    experiment.ImportScalingSettings(scaling_settings);

    // Integration radii: r1 (signal box), r2/r3 (background annulus).
    if (integration_radius_arg) {
        std::vector<float> rr;
        std::stringstream ss(*integration_radius_arg);
        std::string tok;
        while (std::getline(ss, tok, ',')) {
            trim_in_place(tok);
            if (!tok.empty())
                rr.push_back(parse_number_arg<float>(tok.c_str(), "--integration-radius", logger,
                                                     0.1f, 1000.0f));
        }
        float r1, r2, r3;
        if (rr.size() == 1) { r1 = rr[0]; r2 = r1 + 2.0f; r3 = r1 + 4.0f; }
        else if (rr.size() == 3) { r1 = rr[0]; r2 = rr[1]; r3 = rr[2]; }
        else { logger.Error("--integration-radius expects r1 or r1,r2,r3"); return 1; }
        BraggIntegrationSettings bis = experiment.GetBraggIntegrationSettings();
        bis.R1(r1).R2(r2).R3(r3);
        experiment.ImportBraggIntegrationSettings(bis);
        logger.Info("Integration radii set to r1={:.1f} r2={:.1f} r3={:.1f}", r1, r2, r3);
    } else if (!rotation_indexing) {
        // An explicit --integration-radius always wins over the stills default.
        ApplyRugnuxIntegrationRadii(experiment, rotation_indexing);
        logger.Info("Stills integration radii default to r1=6.0 r2=8.0 r3=14.0 (override with --integration-radius)");
    }

    // Adaptive signal radius: measured in the pre-scan and applied there (Rugnux::PreScan). Radii the
    // user set by hand always win, and stills already default to a wide box, so the rule is on for
    // rotation only.
    const bool adaptive_integration_radius =
            !integration_radius_arg
            && adaptive_integration_radius_arg.value_or(rotation_indexing);

    if (forced_prediction_mosaicity_arg) {
        BraggIntegrationSettings bis = experiment.GetBraggIntegrationSettings();
        bis.ForcedPredictionMosaicity_deg(static_cast<float>(*forced_prediction_mosaicity_arg));
        experiment.ImportBraggIntegrationSettings(bis);
        logger.Info("Prediction window fixed at a rocking width of {:.4f} deg; the partiality still uses "
                    "the per-image sigma_M", *forced_prediction_mosaicity_arg);
    }

    if (integration_stencil_arg) {
        const float k = parse_number_arg<float>(integration_stencil_arg->c_str(), "--integration-stencil",
                                                logger, 0.0f, 10.0f);
        BraggIntegrationSettings bis = experiment.GetBraggIntegrationSettings();
        bis.StencilKSigma(k);
        experiment.ImportBraggIntegrationSettings(bis);
        if (!(k > 0.0f))
            logger.Info("Background ring left circular (--integration-stencil 0)");
        else
            logger.Info("Background ring elongated by {:.2f} times the beam's radial streak, per reflection", k);
    }

    if (integrator_mode) {
        BraggIntegrationSettings bis = experiment.GetBraggIntegrationSettings();
        bis.Integrator(*integrator_mode);
        experiment.ImportBraggIntegrationSettings(bis);
        logger.Info("Integrator set to {}", *integrator_mode == IntegratorMode::BoxSum ? "box-sum"
                    : *integrator_mode == IntegratorMode::ProfileGaussian ? "profile (gaussian)"
                    : "profile (empirical)");
    }

    if (integration_d_min_arg) {
        BraggIntegrationSettings bis = experiment.GetBraggIntegrationSettings();
        // 0 spells "no limit" for the sibling resolution options, so it has to mean the same here.
        bis.DMinLimit_A(*integration_d_min_arg > 0.0
                            ? std::optional<float>(static_cast<float>(*integration_d_min_arg))
                            : std::nullopt);
        experiment.ImportBraggIntegrationSettings(bis);
    }

    if (max_hkl_arg) {
        BraggIntegrationSettings bis = experiment.GetBraggIntegrationSettings();
        bis.MaxHKL(static_cast<int>(*max_hkl_arg));
        experiment.ImportBraggIntegrationSettings(bis);
        logger.Info("Predicting reflections with |h|,|k|,|l| <= {} (overriding the per-crystal bound)", *max_hkl_arg);
    }

    if (background_trim_arg) {
        BraggIntegrationSettings bis = experiment.GetBraggIntegrationSettings();
        bis.BackgroundTrimFraction(static_cast<float>(*background_trim_arg));
        experiment.ImportBraggIntegrationSettings(bis);
        logger.Info("Background ring: symmetric trimmed mean at {:.2f} instead of the default high-side clip",
                    *background_trim_arg);
    }

    if (background_clip_arg) {
        BraggIntegrationSettings bis = experiment.GetBraggIntegrationSettings();
        bis.BackgroundClipNSigma(static_cast<float>(*background_clip_arg));
        experiment.ImportBraggIntegrationSettings(bis);
        logger.Info("Background ring: high-side clip at {:.1f} sigma", *background_clip_arg);
    }

    if (overlap_arg || overlap_minpk_arg) {
        BraggIntegrationSettings bis = experiment.GetBraggIntegrationSettings();
        if (overlap_arg)
            bis.Overlap(*overlap_arg);
        if (overlap_minpk_arg)
            bis.OverlapMinPeak(static_cast<float>(*overlap_minpk_arg));
        experiment.ImportBraggIntegrationSettings(bis);
        const auto ovl = bis.GetOverlap();
        logger.Info("Overlapping signal regions: {}", ovl == OverlapMode::Reject
                    ? fmt::format("reject below {:.2f} of the profile", bis.GetOverlapMinPeak())
                    : (ovl == OverlapMode::Exclude ? std::string("exclude the shared pixels")
                                                   : std::string("off")));
    }

    // Auto (ApplyRugnuxExperimentDefaults) unless the flag says otherwise.
    {
        BraggIntegrationSettings bis = experiment.GetBraggIntegrationSettings();
        bis.BackgroundRadialCorrection(background_radial_arg);
        experiment.ImportBraggIntegrationSettings(bis);
    }

    if (flight_path) {
        BraggIntegrationSettings bis = experiment.GetBraggIntegrationSettings();
        bis.FlightPath(flight_path.value());
        experiment.ImportBraggIntegrationSettings(bis);
    }
    // Say what was assumed whether or not the flag was given. Nothing in any file states the medium,
    // so this is the only record that the run made a choice at all - and what the choice is worth
    // runs from 0.2% to 30% at the same incidence angle over this corpus.
    {
        const auto &fp_geom = experiment.GetDiffractionGeometry();
        const auto medium = experiment.GetBraggIntegrationSettings().GetFlightPath();
        const auto fp = sensor_absorption::FlightPathAttenuation::Build(
                medium, fp_geom.GetDetectorDistance_mm(), fp_geom.GetWavelength_A());
        logger.Info("Flight path: {} assumed, {:.4f} attenuation lengths over {:.0f} mm "
                    "({:+.1f}% at 45 deg to the detector normal). No file states the medium; "
                    "--flight-path air|helium|vacuum",
                    medium == FlightPathMedium::Air ? "air"
                        : (medium == FlightPathMedium::Helium ? "helium" : "vacuum"),
                    fp.d_over_L, fp_geom.GetDetectorDistance_mm(),
                    100.0 * (fp.Factor(0.7071068f) - 1.0f));
    }
    // Say what was decided whether or not the flag was given. In auto the correction is applied per
    // image from that image's ice score, so a log that only spoke when asked left no record of whether
    // it ran - and a run whose numbers differ from another's gave no way to see why.
    {
        const auto radial = experiment.GetBraggIntegrationSettings().GetBackgroundRadialCorrection();
        logger.Info("Background ring: radial curvature correction {}",
                    radial.has_value() ? (*radial ? "on" : "off")
                                       : "auto (per image, where the ice score sees a smooth ring)");
    }

    // Detection defaults differ by workflow (RugnuxDefaultSpotFinding); each flag always wins.
    SpotFindingSettings spot_settings = RugnuxDefaultSpotFinding(rotation_indexing);
    spot_settings.signal_to_noise_threshold = sigma_spot_finding;
    spot_settings.photon_count_threshold = photon_count_threshold_spot_finding;
    if (min_pix_per_spot.has_value())
        spot_settings.min_pix_per_spot = min_pix_per_spot;
    if (adaptive_spots.has_value())
        spot_settings.adaptive_threshold = *adaptive_spots;
    spot_settings.high_resolution_limit = d_min_spot_finding;
    spot_settings.false_pixels_per_frame = false_pixels_per_frame;
    spot_settings.low_resolution_limit = d_max_spot_finding;

    // Validate the assembled spot-finding settings the same way the online receivers do (broker and
    // receiver call this same function). It enforces the cross-field constraints that per-argument
    // bounds cannot express - in particular that the low-resolution limit is coarser than the
    // high-resolution limit, so --spot-low-resolution below the high-res cut no longer silently
    // rejects every pixel.
    try {
        DiffractionExperiment::CheckDataProcessingSettings(spot_settings);
    } catch (const std::exception &e) {
        logger.Error("Invalid spot-finding settings: {}", e.what());
        return 1;
    }

    // Run the shared full-analysis workflow (rotation indexing + scaling/merging live in
    // Rugnux; the experiment above carries all algorithm settings).
    ProcessConfig config;
    config.mode = ProcessMode::FullAnalysis;
    config.provenance = output_provenance;
    config.start_image = start_image;
    config.end_image = end_image;
    config.stride = image_stride;
    config.nthreads = nthreads;
    config.nthreads_auto = nthreads_auto;
    config.spot_finding = spot_settings;
    config.rotation_indexing = rotation_indexing;
    config.two_pass_rotation = two_pass_rotation;
    config.detect_beam_stop = detect_beam_stop;
    config.beam_center_check = beam_center_check;
    config.adaptive_integration_radius = adaptive_integration_radius;
    config.counts_in_adu = input_is_smv || input_is_marccd || input_is_xtc
                           || (input_is_crystfel && !crystfel_reader.CountsInPhotons());
    config.rotation_postrefine_geometry = rotation_postrefine_geometry;
    // Measure the spot budget from the data unless the user pinned it.
    config.measure_spot_budget = !max_spot_count_override.has_value();
    config.rotation_scale = rotation_scale;
    config.rotation_indexing_image_count = rotation_indexing_image_count;
    config.prepass_fraction = prepass_fraction;
    config.forced_rotation_lattice = forced_rotation_lattice;
    config.refine_geometry = refine_geometry;
    config.run_scaling = run_scaling;
    config.scaling_iter = scaling_iter;
    config.reference_data = reference_data;
    config.reference_has_free_flags = reference_has_free_flags;
    config.reference_cell = reference_cell;
    if (reference_space_group != nullptr)
        config.reference_space_group = *reference_space_group;
    if (!dump_observations.empty())
        config.observation_dump = [path = dump_observations](const std::string &text) {
            std::ofstream(path) << text;
        };
    config.export_unmerged = export_unmerged;
    config.export_unmerged_partials = export_unmerged_partials;
    config.model = model;
    config.force_mr = !mr_model.empty();
    // When merging, the merged reflections (.mtz/.cif) are the wanted output; skip the large
    // _process.h5 unless explicitly requested. Without merging, the _process.h5 is the only output.
    std::optional<ProcessFileSink> sink;
    if (!output_prefix.empty() && (run_scaling ? write_process_h5_flag : true))
        config.image_sink = &sink.emplace(output_prefix);
    config.finalist_ledger = finalist_ledger_flag;
    config.live = broker_feed || simulate_live;
    config.fast_live = fast_live && config.live;
    if (config.fast_live)
        config.adaptive_integration_radius = false;   // as MakeRugnuxLiveSetup
    if (simulate_live)
        logger.Info("Simulated live collection: image i readable (i+1) x {:.1f} ms after the run starts",
                    simulated_frame_time.count() / 1000.0);
    // As the broker does when a model is uploaded, before the collection it is for starts.
    if (simulate_live && model)
        WarmUpModelValidation(model, static_cast<size_t>(config.nthreads), logger);
    simulated_start = std::chrono::steady_clock::now();

    Rugnux process(reader, experiment, *dataset->pixel_mask, config);

    g_active_process = &process;
    std::signal(SIGINT, handle_sigint);

    ProcessResult result;
    try {
        result = process.Run(console.get());
    } catch (const NoLatticeFound &e) {
        // No crystal in these frames is a result, and the report says so - VERDICT= FAILED with
        // NO_LATTICE - before the run exits as failed.
        logger.Error("No crystal lattice found: {}", e.reason);
        ProcessResult failed;
        failed.warnings.push_back({PathologyCode::NO_LATTICE, "No crystal lattice was found: " + e.reason});
        failed.powder = process.GetPowderRings();
        failed.used_beam_x_pxl = experiment.GetBeamX_pxl();
        failed.used_beam_y_pxl = experiment.GetBeamY_pxl();
        failed.used_distance_mm = experiment.GetDetectorDistance_mm();
        const auto direct = experiment.GetDiffractionGeometry().GetDirectBeam_pxl();
        failed.used_direct_beam_x_pxl = direct.first;
        failed.used_direct_beam_y_pxl = direct.second;
        provenance.wall_time_s = std::chrono::duration<double>(
                std::chrono::steady_clock::now() - invocation_start).count();
        sink.reset();   // exit() runs no destructor: the _process.h5 is closed here
        // The per-image analysis of every frame (NoLatticeFound::per_image), where a run that indexed
        // nothing puts it: the _process.h5 and the per-image table.
        if (e.per_image && !output_prefix.empty()) {
            try {
                WriteRugnuxOutputs(*e.per_image, output_prefix, output_provenance,
                                   static_cast<size_t>(std::max(1, nthreads)), logger);
            } catch (const std::exception &w) {
                logger.Error("Writing the per-image analysis failed: {}", FailureText(w));
            }
        }
        const ReportDocument doc = WriteResultReport(output_prefix, input_file, experiment, failed, logger,
                                                     provenance);
        console->Fail();
        PrintSummary(*console, doc, output_prefix, files_since, provenance.wall_time_s);
        exit(EXIT_FAILURE);
    } catch (const std::exception &e) {
        logger.Error("Processing failed: {}", FailureText(e));
        sink.reset();
        exit(EXIT_FAILURE);
    }
    g_active_process = nullptr;

    // Every file the run made, from what it returned.
    if (!output_prefix.empty()) {
        try {
            WriteRugnuxOutputs(result, output_prefix, output_provenance, static_cast<size_t>(std::max(1, nthreads)),
                               logger);
        } catch (const std::exception &e) {
            logger.Error("Processing failed: {}", FailureText(e));
            exit(EXIT_FAILURE);
        }
    }

    // The results report, next to the .mtz/.cif/.hkl. Written on every run with an output prefix -
    // including --no-merge, which still determined an indexing and geometry result worth recording.
    // The wall time is the whole invocation, which is more than result.total_time_s: that one starts
    // inside Rugnux::Run, so it counts neither opening the file nor setting up the analysis.
    provenance.wall_time_s = std::chrono::duration<double>(
            std::chrono::steady_clock::now() - invocation_start).count();
    TimingMark report_mark(logger, "results report");
    const ReportDocument doc = WriteResultReport(output_prefix, input_file, experiment, result, logger, provenance);
    report_mark.Stop();

    // The space-group search is rendered here (not in the library) so the viewer does not emit it and
    // the CLI owns the format. The report carries it too, in its developer rendering.
    if (result.space_group_search.has_value())
        logger.Info("Space-group search:\n{}", SearchSpaceGroupResultToText(*result.space_group_search));

    if (!result.merge_statistics_text.empty())
        logger.Info("Merging statistics:\n{}", result.merge_statistics_text);

    // Report statistics. The time is the whole run - a rotation two-pass integrates everything twice,
    // and the pre-scan runs before either pass, so the per-pass number understated it by 3-4x. The rate
    // and throughput stay per-pass: they say how fast rugnux moves through images, which running a
    // second pass does not change.
    logger.Info("Processing time: {:.2f} s", result.total_time_s);
    logger.Info("Total wall time: {:.2f} s", provenance.wall_time_s);
    if (result.pass_count > 1)
        logger.Info("  last pass:     {:.2f} s (of {} passes)",
                                 result.processing_time_s, result.pass_count);
    logger.Info("Frame rate:      {:.2f} Hz", result.frame_rate_hz);
    logger.Info("Total throughput:{:.2f} MB/s", result.throughput_MBs);
    if (result.indexing_rate.has_value())
        logger.Info("Indexing rate:   {:.2f}%", result.indexing_rate.value() * 100.0);
    // Final one-line summary of the adopted crystal (whether de-novo determined or fixed with -S),
    // so it is not buried in the space-group-search block (which is de-novo only) or only in the mmCIF.
    // Only when something actually indexed: with a zero indexing rate the cell is whatever the lattice
    // search happened to return and no reflection was measured on it, so printing it as the run's answer
    // states a result the data do not support.
    // A rotation run can index the sweep as a whole with no frame indexing on its own.
    const bool anything_indexed = result.indexing_rate.value_or(0.0f) > 0.0f || result.rotation_lattice_found;
    if (result.space_group.has_value() && anything_indexed) {
        std::string line = fmt::format("Space group:     {} (No. {})", result.space_group->short_name(),
                                       result.space_group->number);
        // Name every group the data cannot separate, not just the representative. Some pairs share
        // their whole absence pattern - an enantiomorphic pair (P4_1 vs P4_3), or I23 vs I2_13 and
        // I222 vs I2_12_12_1, where the screw condition h00: h=2n is already implied by the
        // I-centering - so the choice among them is a convention, not a measurement. The search
        // reports the representative as the lowest space-group number; saying so here keeps the
        // summary from claiming a decision the diffraction did not make.
        // Not the adopted group itself: where --model has taken the enantiomorph, the group now
        // reported is the one the search listed as the alternative, and naming it as its own
        // alternative would read as a decision that was not made.
        bool named_alternative = false;
        if (result.space_group_search.has_value())
            for (const auto &alt : result.space_group_search->alternatives)
                if (alt.number != result.space_group->number) {
                    line += fmt::format(" or {} (No. {})", alt.short_name(), alt.number);
                    named_alternative = true;
                }
        if (named_alternative)
            line += " - indistinguishable from these data";
        logger.Info("{}", line);
    }
    if (result.consensus_cell.has_value() && anything_indexed) {
        const auto &c = result.consensus_cell.value();
        logger.Info("Unit cell:       a={:.2f} b={:.2f} c={:.2f} alpha={:.2f} beta={:.2f} gamma={:.2f}",
                                 c.a, c.b, c.c, c.alpha, c.beta, c.gamma);
    }
    if (result.indexing_rate.has_value() && !anything_indexed)
        logger.Info("No image indexed - no crystal lattice was determined from this dataset");

    // Each stage timer measures wall time inside one worker, so it counts the time that worker spent
    // BLOCKED on a contended resource - above all the GPU - as well as its own work. Dividing that by
    // the worker count, as this used to, assumes every worker was busy for the whole loop; the loop
    // in fact runs at a fraction of the workers it was given (a third of them on a large detector,
    // less on a small one), so the printed cost came out low by that same factor.
    //
    // Report the share instead. A stage's fraction of a worker's own per-image time is what that
    // stage is responsible for, whatever the contention was, and spending it against the loop's wall
    // time per image gives a number that is attributable and that sums to the loop. The worker mean
    // itself is printed at the end, because the gap between it and the wall is the waiting, and that
    // is worth seeing rather than dividing away.
    const auto &t = result.mean_processing_time;
    const double loop_ms = (result.images_processed > 0 && result.image_loop_time_s > 0.0)
            ? result.image_loop_time_s * 1e3 / static_cast<double>(result.images_processed) : 0.0;
    const double worker_mean_ms = std::isfinite(t.processing) ? t.processing * 1e3 : 0.0;
    auto stage = [&](const char *name, float mean_s) {
        // A stage that never ran has no mean at all - the per-image indexing and scaling timers are
        // never fed on the two-pass rotation path, where the lattice is forced and the merge happens
        // outside the image loop. Say nothing rather than printing nan.
        return (std::isfinite(mean_s) && worker_mean_ms > 0.0)
               ? fmt::format(" {} {:.2f}", name, mean_s * 1e3 / worker_mean_ms * loop_ms) : std::string();
    };
    logger.Info("Per-image cost (ms of loop wall, {} workers):{}{}{}{}{}{}{}{}{}{}{}   [{:.1f} ms inside a worker; "
                "the difference is waiting]",
                result.image_loop_threads > 0 ? result.image_loop_threads : nthreads,
                stage("decompress", t.compression), stage("preprocess", t.preprocessing),
                stage("azint", t.azint), stage("spot-finding", t.spot_finding),
                stage("indexing", t.indexing), stage("refinement", t.refinement),
                stage("indexing-analysis", t.indexing_analysis), stage("prediction", t.bragg_prediction),
                stage("integration", t.integration), stage("scaling", t.image_scale),
                stage("total", t.processing), worker_mean_ms);

    // The stage timers only cover the per-image loop. On a rotation run the first-pass indexing and the
    // scaling/merging sit outside it and can be a large share of the run, so report the loop against the
    // whole run instead of leaving the difference unexplained. Both are the last pass only: a two-pass
    // rotation run does all of this twice.
    if (result.images_processed > 0 && result.image_loop_time_s > 0.0) {
        const double loop_ms = result.image_loop_time_s * 1e3 / static_cast<double>(result.images_processed);
        const double outside_s = result.processing_time_s - result.image_loop_time_s;
        logger.Info("Per-image wall:  {:.2f} ms in the image loop ({:.2f} s); "
                                 "{:.2f} s outside it (first-pass indexing, scaling/merging) [last pass]",
                                 loop_ms, result.image_loop_time_s, std::max(0.0, outside_s));
    }

    if (result.cancelled)
        logger.Warning("Processing was cancelled after {} images", result.images_processed);

    console->Finish();
    PrintSummary(*console, doc, output_prefix, files_since, provenance.wall_time_s);
    return EXIT_SUCCESS;
}

int main(int argc, char **argv) {
    try {
        // Before anything creates a CUDA context, which fixes the flags for the device. A thread
        // waiting on the GPU then sleeps instead of spinning on a core - measured on a 16M rotation
        // run, a fifth of all CPU time went to that spinning, with no change in wall time either way.
        // --no-gpu is looked for here, ahead of the parser, because that already asks CUDA for the devices.
        UsePrivateCudaJitCacheIfNeeded();
        bool no_gpu = false;
        for (int i = 1; i < argc; i++)
            if (std::strcmp(argv[i], "--no-gpu") == 0)
                no_gpu = true;
        if (no_gpu)
            hide_gpus();
        set_gpu_blocking_sync();
        enable_gpu_numa_binding();
        const int ret = RunRugnux(argc, argv, no_gpu);
        // Everything that used a card has been destroyed with the run.
        release_gpu_contexts();
        return ret;
    } catch (const std::exception &e) {
        Logger("rugnux").Error("{}", FailureText(e));
        return EXIT_FAILURE;
    }
}