Jungfraujoch/rugnux/ModelValidation.h

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

#pragma once

#include <optional>
#include <string>
#include <vector>

#include "../common/Reflection.h"   // MergedReflection
#include "../common/UnitCell.h"

class Logger;

// Result of validating merged intensities against an atomic model.
struct ModelValidationResult {
    bool ok = false;
    double r_work = 0.0;
    double r_free = 0.0;
    double k_sol = 0.0;
    double b_sol = 0.0;
    double k_overall = 0.0;
    int n_work = 0;
    int n_free = 0;
    double mean_atom_density_sigma = 0.0;  // mean 2Fo-Fc value at atom centres, in sigma
    std::string maps_prefix;               // where the .ccp4 / _maps.mtz were written
};

// Given merged intensities and a PDB atomic model, scale the model structure factors (with an
// optimized flat bulk-solvent contribution and an overall anisotropic B) to the observed
// amplitudes, then report R-work / R-free and write 2Fo-Fc and Fo-Fc electron-density maps
// (CCP4) plus an MTZ of map coefficients next to output_prefix.
//
// No refinement of the structure itself is done. The model is only re-fractionalized into the
// data unit cell (a cheap rigid cell adjustment) so a deposited model with a slightly different
// cell still lines up with the processed data. Returns ok=false (and logs) on any failure.
// data_space_group_number is the space group the data was merged in. If it is the enantiomorph of
// the model's space group (e.g. data P4(1)2(1)2, model P4(3)2(1)2 - indistinguishable from merged
// intensities), the observed reflections are reindexed into the model's hand before comparison.
//
// probe_indexing_ambiguity controls how a merohedral (alternative-indexing) ambiguity is resolved.
// Pass false when a reference (MTZ) already fixed the indexing - the data are then kept in that
// authoritative indexing. Pass true (model only, no reference) to resolve it here as a fallback, by
// fitting each candidate reindexing to the model and keeping the lowest R-free. Holohedral crystals
// (no twin laws) are unaffected either way.
ModelValidationResult ValidateAgainstModel(const std::vector<MergedReflection> &merged,
                                           const UnitCell &cell,
                                           const std::string &model_path,
                                           const std::string &output_prefix,
                                           Logger &logger,
                                           std::optional<int> data_space_group_number = std::nullopt,
                                           bool probe_indexing_ambiguity = true);