Jungfraujoch/image_analysis/scale_merge/ReindexAmbiguity.h

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

#pragma once

#include <functional>
#include <map>
#include <vector>

#include "gemmi/symmetry.hpp"

#include "HKLKey.h"
#include "../../common/DiffractionExperiment.h"
#include "../../common/Reflection.h"
#include "../../common/UnitCell.h"

// Resolving the indexing ("alternative indexing" / reindexing) ambiguity: when the lattice symmetry
// is higher than the crystal Laue symmetry (merohedral / pseudo-merohedral), a crystal can be validly
// indexed in several ways related by reindexing operators. The right one is picked by agreement with a
// reference (reference-MTZ intensities or a model), so no reference-free ambigator (cosym) is needed.
//
// This is distinct from the screw-axis / enantiomorph ambiguity (P4_1 vs P4_3): that leaves the merged
// intensities unchanged, so it is never resolved here — it is adopted from the reference/model.

// The candidate reindexing operators = twin laws = cosets of the crystal point group in the lattice
// symmetry. Empty when the lattice symmetry equals the crystal Laue symmetry (holohedral crystal),
// i.e. there is no indexing ambiguity. Identity is NOT included in the returned list.
std::vector<gemmi::Op> ReindexAmbiguityOperators(const UnitCell &cell, int space_group_number,
                                                 double max_obliquity_deg = 2.0);

// A copy of `merged` with each Miller index transformed by `op` (the intensities are unchanged).
std::vector<MergedReflection> ReindexReflections(const std::vector<MergedReflection> &merged,
                                                 const gemmi::Op &op);

struct ReindexChoice {
    gemmi::Op op = gemmi::Op::identity();   // the winning operator (identity = keep the current indexing)
    bool is_identity = true;
    double score = 0.0;                     // score of the winning operator
    double identity_score = 0.0;            // score with no reindex, for comparison / logging
    int n_candidates = 1;                   // identity + twin laws that were tried
};

// Pick the reindexing operator (identity or one of the twin laws) that MAXIMIZES `score(reindexed)`.
// `score` is higher-is-better (e.g. correlation against a reference, or minus the R-free against a
// model). Returns identity when there is no ambiguity or identity scores best.
ReindexChoice ChooseReindex(const std::vector<MergedReflection> &merged,
                            const UnitCell &cell, int space_group_number,
                            const std::function<double(const std::vector<MergedReflection> &)> &score,
                            double max_obliquity_deg = 2.0);

// Ready-made scorer: Pearson correlation of merged intensities against a reference set, matched by the
// Friedel-merged (Laue) ASU index in `space_group_number`. Returns 0 when too few reflections match.
double ReferenceIntensityCC(const std::vector<MergedReflection> &merged,
                            const std::vector<MergedReflection> &reference,
                            int space_group_number);

// Per-image resolver for serial stills. Each crystal is indexed independently in one of the
// merohedrally-equivalent hands at random, so the ambiguity has to be broken per image (unlike rotation
// data, which resolve it once for the whole merged set with ChooseReindex above). Holds the external
// reference intensities and the crystal's twin-law operators, and reindexes one image's reflections into
// the hand best-correlated with the reference. This runs in the per-image pipeline at integration time,
// decoupled from scaling.
class ReindexAmbiguityResolver {
    const ScalingSettings s;
    const HKLKeyGenerator hkl_key_generator;
    std::map<HKLKey, double> reference_data;
    // Twin-law reindexing operators (identity excluded). Empty = no ambiguity (holohedral crystal) or the
    // cell/space group is unknown, in which case Resolve() is a no-op.
    std::vector<gemmi::Op> ops;

    bool Accept(const Reflection &r) const;
    // Pearson correlation of this image's partiality/Lorentz-corrected intensities against the reference,
    // matched by ASU index under `op`. Scale-invariant (the unknown per-image scale cancels). NaN when
    // too few reflections match.
    double ReferenceCC(const std::vector<Reflection> &reflections, const gemmi::Op &op) const;

public:
    // The reference must be an external, correctly-handed dataset (not the data's own running merge).
    ReindexAmbiguityResolver(const DiffractionExperiment &x, const std::vector<MergedReflection> &reference);

    // Reindex this image's reflections in place into the hand best-correlated with the reference (done
    // once per image, for good). No-op when there is no ambiguity.
    void Resolve(std::vector<Reflection> &reflections) const;
};