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;

    // 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);