Jungfraujoch/image_analysis/geom_refinement/PostRefine.h

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

#pragma once

#include <array>
#include <optional>
#include <vector>

#include "../../common/DiffractionGeometry.h"
#include "../../common/CrystalLattice.h"
#include "../../common/GoniometerAxis.h"
#include "../../common/UnitCell.h"
#include "../../common/Logger.h"
#include "../IntegrationOutcome.h"
#include "gemmi/symmetry.hpp"

// Post-integration geometry refinement for rotation data. Unlike the at-indexing XtalOptimizer, this runs
// AFTER integration/merge, where each reflection has an OBSERVED rocking centroid phi_obs (the intensity-
// weighted mean goniometer angle over the frames it spans) and an observed spot position. One JOINT fit
// refines the crystal (orientation, cell, rotation axis) and the detector (distance, beam centre) together
// against two residuals:
//   * an Ewald excitation residual evaluated at phi_obs (distance-independent) -> pins the absolute cell
//     scale that the positional residual leaves degenerate with the distance. Because phi_obs is the real
//     rocking angle (not a frame centre) it is unbiased.
//   * the positional detector<->reciprocal residual at each partial's observed spot -> pins the distance.
// Where there are more reflections than the fit's caps, the strongest by I/sigma are the ones kept;
// inside the fit every reflection carries the same weight.

struct PostRefineResult {
    bool ok = false;
    DiffractionGeometry geom;                 // refined (distance / beam left as configured)
    UnitCell cell{};                          // refined unit cell
    int events_used = 0;
    int obs_used = 0;
    double distance_before_mm = 0.0, distance_after_mm = 0.0;
    double beam_x_before_px = 0.0, beam_x_after_px = 0.0;   // refined beam centre (GEOM mode)
    double beam_y_before_px = 0.0, beam_y_after_px = 0.0;
    // The joint fit is one decision - the crystal and the detector are refined together and committed
    // together - so these two are always equal. Both are kept because the report names them separately.
    bool cell_refined = false;                // the joint fit passed cross-validation (crystal half)
    bool detector_refined = false;            // the joint fit passed cross-validation (detector half)
    // GONIOMETER ROTATION SCALE: the factor by which the stage actually turned relative to the angle
    // stored in the file (which is the COMMANDED value, hence a stage calibration error is invisible in
    // the header). Fitted after the joint fit as a single free parameter, with the crystal and the axis
    // direction held at their committed values. Always the fitted value; 1.0 = header and stage agree.
    double rotation_scale = 1.0;
    // Whether the fit passed every test needed to ACT on it: enough sweep and events, a significant and
    // physically relevant size, and the same k from every fifth of the sweep. Only then is it applied.
    bool rotation_scale_suspect = false;
};

struct PostRefineSettings {
    gemmi::CrystalSystem crystal_system = gemmi::CrystalSystem::Triclinic;
    bool refine_geometry = false;     // XtalOptimizer-equivalent: the crystal (from phi_obs and the observed
                                      // spot positions) and the detector distance + beam centre, in one
                                      // cross-validated fit. The only supported refinement mode.
    double excitation_weight = 1.0;   // weight of the phi/excitation residual vs the positional one
    int min_events = 50;
    int num_threads = 1;
    // An independent measurement of the beam centre in pixels, where the run has one (rugnux's pre-scan
    // fit to the isotropy of the scattered background, which runs on every rotation run). The fit bounds
    // how far it may move the beam from whichever of this and the nominal centre is NEARER; see
    // BEAM_BOUND_PXL in PostRefine.cpp for why the nominal centre alone is not enough to bound it.
    std::optional<std::array<double, 2>> measured_beam_px;
};

// nominal_geom / reference_latt: the current detector geometry and the phi=0 reference lattice (orientation
// + cell) from rotation indexing. outcomes: the per-image integrated reflections (observed_x/y, I, sigma,
// image_number). axis: the goniometer. Returns ok=false (geometry untouched) on failure.
PostRefineResult PostRefineRotationGeometry(const std::vector<IntegrationOutcome> &outcomes,
                                            const GoniometerAxis &axis,
                                            const DiffractionGeometry &nominal_geom,
                                            const CrystalLattice &reference_latt,
                                            const PostRefineSettings &settings,
                                            Logger &logger);