Jungfraujoch/image_analysis/scale_merge/ResolutionCutoff.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/Logger.h"
#include "../../common/Reflection.h"   // MergedReflection

// Automatic high-resolution cutoff from the CC1/2 fall-off of the merged half-sets (DIALS-style).
// The merge itself, the error model and the per-image _process.h5 are left untouched - only the
// written reflections and the reported shell table should be trimmed to the returned d_cut.
//
// Method (see docs/rugnux_resolution_cutoff_design.md): bin CC1/2 against s = 1/d^2 in fine bins,
// fit a logistic CC1/2(s) = 1/(1+exp(k*(s-s0))) to the contiguous-from-low-res fall-off, take the s
// where the fit crosses cc_target, then extend by one mean (10-shell) shell width in s ("one shell
// too far", generous). d_cut is nullopt when the fit is degenerate (too few bins, flat/non-monotone)
// or CC1/2 never falls below cc_target inside the measured range - the caller then keeps the full
// range. cc_target in (0,1); merged must carry finite I_half[0]/I_half[1] to contribute.
struct ResolutionCutoffResult {
    std::optional<double> d_cut;   // high-resolution limit (A); nullopt => keep the full range
    std::string note;              // human-readable description of the decision (for logging)
};

ResolutionCutoffResult ComputeCCHalfLogisticCutoff(const std::vector<MergedReflection> &merged,
                                                   double cc_target, Logger &logger);