Jungfraujoch/common/ScalingSettings.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 "JFJochException.h"

enum class IntensityFormat { Text, mmCIF, MTZ};

// How the high-resolution cutoff for the written reflections and the reported shell table is chosen
// when no explicit --scaling-high-resolution is given. Off = keep the full (detector-edge) range;
// CCHalfLogistic = fit the CC1/2 fall-off and cut one shell past cc_target (DIALS-style, generous).
enum class ResolutionCutoffMethod { Off, CCHalfLogistic };

class ScalingSettings {
    bool refine_b = false;
    double max_b = 200.0;
    double min_b = -50.0;

    bool refine_wedge = false;

    bool merge_friedel = true;
    std::optional<double> high_resolution_limit_A;
    std::optional<double> wedge_for_scaling;
    std::optional<double> forced_mosaicity;   // diagnostic: fix the scaling mosaicity (deg) instead of the per-image seed
    double min_partiality = 0.02;
    // Capture-aware systematic uncertainty for the rot3d combine: a full reconstructed from only
    // a fraction f<1 of its rocking curve is extrapolated, and the unobserved (1-f) carries a
    // systematic error ~coeff*(1-f)*I that plain counting sigma misses. 0 = off (baseline).
    double capture_uncertainty_coeff = 0.0;
    double min_cc_for_image = 0.0;
    double outlier_reject_nsigma = 0.0; // per-observation merge outlier rejection (XDS/DIALS-style); 0 = off, e.g. 6 enables

    // Scale fulls: after the rotation 3D combine, refit a per-frame scale on the combined fulls (XDS
    // order). Only used by the rotation path (RotationScaleMerge).
    bool scale_fulls = false;

    // Absorption surface: after scaling the rot3d fulls, fit a smooth multiplicative correction
    // over the diffracted-beam direction in the crystal frame, refined over this many iterations.
    // 0 = off. Negligible at hard X-rays / thin crystals, but matters at low energy. No-op without rot3d.
    int absorption_iter = 0;

    // Smooth the per-frame scale G across frames (centered moving average of log G) before the rot3d
    // combine, so a rocking event's partials share a consistent scale. Given as a ROTATION RANGE in
    // degrees (like XDS DELPHI), converted to an odd frame window from the oscillation step; this keeps
    // the smoothing physical (independent of frame slicing). 0 = off. A no-op without rot3d.
    double smooth_g_deg = 0.0;

    double rfree_fraction = 0.05;
    IntensityFormat intensity_format = IntensityFormat::mmCIF;

    // Automatic high-resolution cutoff for the written reflections + reported shells (not the scaling
    // or the error model, and not the per-image _process.h5). Applied only when no explicit
    // high_resolution_limit_A is set - that manual limit always wins and disables the auto-cut.
    ResolutionCutoffMethod resolution_cutoff = ResolutionCutoffMethod::CCHalfLogistic;
    double resolution_cc_target = 0.30;   // CC1/2 value defining the fall-off limit before the +1 shell
    int report_shell_count = 10;          // number of resolution shells in the reported statistics table

    bool scaling_regularize = false;
public:
    ScalingSettings& RefineB(bool input);
    ScalingSettings& RefineRotationWedge(bool input);
    ScalingSettings& RotationWedgeForScaling(std::optional<double> input);
    ScalingSettings& MergeFriedel(bool input);
    ScalingSettings& HighResolutionLimit_A(double limit);
    ScalingSettings& HighResolutionLimit_A(std::optional<double> limit);   // nullopt clears the limit
    ScalingSettings& MinPartiality(double min_partiality);
    ScalingSettings& ForcedMosaicity(std::optional<double> input);
    ScalingSettings& CaptureUncertaintyCoeff(double input);
    ScalingSettings& MinCCForImage(double min_cc_for_image);
    ScalingSettings& OutlierRejectNsigma(double input);
    ScalingSettings& ScaleFulls(bool input);
    ScalingSettings& AbsorptionIter(int input);
    ScalingSettings& SmoothGDegrees(double input);

    ScalingSettings& RfreeFraction(double input);
    ScalingSettings& FileFormat(IntensityFormat input);
    ScalingSettings& ScalingRegularize(bool input);

    ScalingSettings& ResolutionCutoff(ResolutionCutoffMethod input);
    ScalingSettings& ResolutionCCTarget(double input);
    ScalingSettings& ReportShellCount(int input);

    [[nodiscard]] bool GetRefineB() const;
    [[nodiscard]] bool GetRefineWedge() const;

    [[nodiscard]] double GetMinB() const;
    [[nodiscard]] double GetMaxB() const;

    [[nodiscard]] double GetMinMosaicity() const;
    [[nodiscard]] double GetDefaultMosaicity() const;
    [[nodiscard]] double GetMaxMosaicity() const;

    [[nodiscard]] double GetMinWedge() const;
    [[nodiscard]] std::optional<double> GetRotationWedgeForScaling() const;
    [[nodiscard]] double GetMaxWedge() const;

    [[nodiscard]] bool GetMergeFriedel() const;

    [[nodiscard]] std::optional<double> GetHighResolutionLimit_A() const;

    [[nodiscard]] double GetMinPartiality() const;
    [[nodiscard]] std::optional<double> GetForcedMosaicity() const;
    [[nodiscard]] double GetCaptureUncertaintyCoeff() const;
    [[nodiscard]] double GetMinCCForImage() const;
    [[nodiscard]] double GetOutlierRejectNsigma() const;
    [[nodiscard]] bool GetScaleFulls() const;
    [[nodiscard]] int GetAbsorptionIter() const;
    [[nodiscard]] double GetSmoothGDegrees() const;

    [[nodiscard]] double GetRfreeFraction() const;
    [[nodiscard]] IntensityFormat GetFileFormat() const;
    [[nodiscard]] bool GetScalingRegularize() const;

    [[nodiscard]] ResolutionCutoffMethod GetResolutionCutoff() const;
    [[nodiscard]] double GetResolutionCCTarget() const;
    [[nodiscard]] int GetReportShellCount() const;
};