Jungfraujoch/image_analysis/geom_refinement/XtalOptimizer.h

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

#pragma once

#include <optional>
#include <span>

#include "../common/GoniometerAxis.h"
#include "../common/CrystalLattice.h"
#include "../common/DiffractionGeometry.h"
#include "../common/SpotToSave.h"
#include "gemmi/symmetry.hpp"

struct XtalOptimizerData {
    DiffractionGeometry geom;
    CrystalLattice latt;
    gemmi::CrystalSystem crystal_system = gemmi::CrystalSystem::Triclinic;
    int64_t min_spots = 8;

    float min_length_A = 5.0;
    float max_length_A = 500.0;
    float min_angle_deg = 60.0f;
    float max_angle_deg = 120.0f;

    bool refine_beam_center = true;
    bool refine_detector_angles = false;
    bool refine_unit_cell = true; // This refines unit cell size + angles - orientation is always refined
    bool refine_rotation_axis = false;

    bool index_ice_rings = true;

    // Weight each spot by how strong it is for its resolution, so that low-confidence spots contribute
    // without driving the fit (see SpotConfidenceWeights). Off by default: the indexers call this with a
    // spot list they have already selected, it is the per-image refinement that gets the raw list.
    bool weight_spots_by_confidence = false;

    // Stopping rule. max_iterations > 0 bounds the solver by ITERATIONS, which is reproducible;
    // otherwise it is bounded by max_time, wall-clock seconds, which is not - the same image refines
    // to a different answer on a busier machine. Online acquisition needs the wall-clock bound because
    // its budget is real; offline reprocessing wants the reproducible one.
    float max_time = 1.0;
    int max_iterations = 0;

    std::optional<GoniometerAxis> axis;

    // The rocking geometry, for the acceptance gate's dead zone alone - NOT for back-rotation. A
    // refinement that holds a single frame does not back-rotate (the frame's angle is a gauge its
    // orientation block absorbs) and so passes no `axis`, but the spots on that frame still
    // diffracted at different angles spanning the exposure, and the gate still has to be told it
    // does not know which. Left unset - or a wedge below the coarse-slicing trigger - the gate is
    // the plain fractional-index test.
    std::optional<Coord> rocking_spindle;
    float rocking_wedge_deg = 0.0f;

    // output
    std::optional<double> beam_corr_x;
    std::optional<double> beam_corr_y;

    // For rotation only optimizer
    std::optional<double> angle_corr;
    std::optional<Coord> angle_axis;
};

// num_threads sets the Ceres solver thread count for the internal least-squares refine. It defaults
// to 1 because XtalOptimizer is usually called from many threads at once; raise it only when a caller
// runs a small number of refinements concurrently and wants each to use several cores.
bool XtalOptimizer(XtalOptimizerData &data, std::span<const std::vector<SpotToSave>> spots,
                   int num_threads = 1);
// Single frame. Not the same as passing {spots} to the overload above: a braced list copies the spot
// list, its elements being const, which on the per-image path is the whole list once per image.
bool XtalOptimizer(XtalOptimizerData &data, const std::vector<SpotToSave> &spots, int num_threads = 1);
bool XtalOptimizerRotationOnly(XtalOptimizerData &data, const std::vector<SpotToSave> &spots, float tolerance);

// The widest of the three fractional-index gates XtalOptimizer fits through. Its first pass selects
// spots on this one and its last pass on 0.1, so the spots between the two are carried into the fit
// and then dropped from it: this is the population a converged solve does NOT optimise.
constexpr float XTAL_OPTIMIZER_WIDE_TOLERANCE = 0.3f;