Jungfraujoch/image_analysis/WriteReflections.h

// SPDX-FileCopyrightText: 2025 Paul Scherrer Institute
// SPDX-License-Identifier: GPL-3.0-only

#pragma once

#include <string>
#include <vector>

#include "../common/Reflection.h"
#include "../common/UnitCell.h"
#include "../common/DiffractionExperiment.h"
#include "../common/JFJochMessages.h"
#include "IntegrationOutcome.h"

#include <gemmi/mtz.hpp>

struct MergeStatistics;
struct TwinningAnalysisResult;

// The error model as it is reported, already formatted. `isa` is the whole-range 1/sqrt(a*b), the
// same quantity XDS's ISa denotes, so a file written here is directly comparable with a CORRECT.LP;
// `isa_asymptotic` is the strong-reflection tier, which only the rotation path has. `a` and `b` are
// in XDS's convention, sigma^2 = a*(sigma0^2 + b*I^2). Empty strings are written as unknown.
struct ErrorModelReport {
    std::string isa;
    std::string isa_asymptotic;
    std::string a;
    std::string b;
};

// What the reflection files record about where they came from, beyond the experiment itself and the
// Rugnux version and commit: the MTZ HISTORY records and the mmCIF's _software and
// _jfjoch_provenance. Empty strings are left out.
struct OutputProvenance {
    std::string command_line;
    std::string input_file;        // the input as found on disk, absolute
    std::string input_identity;    // a cheap identifier of it: size and modification time
    std::string collection_date;   // as the input states it (NXmx /entry/start_time), ISO-8601
};

// The merged reflections, their statistics and the experiment, as one PDBx/mmCIF data block.
// nthreads: workers for the per-reflection row formatting, which is the bulk of the file.
void WriteMmcifReflections(const std::vector<MergedReflection> &reflections,
                           const UnitCell &unitCell,
                           const DiffractionExperiment &experiment,
                           const MergeStatistics &statistics,
                           const ErrorModelReport &error_model,
                           const TwinningAnalysisResult &twinning,
                           const OutputProvenance &provenance,
                           const std::string &filename,
                           size_t nthreads);

// The merged MTZ as a structured END-message block: the columns, metadata and HISTORY records that
// WriteMtzReflections writes, for jfjoch_writer to write the same file (WriteMergedMtz,
// writer/WriteRugnuxFiles.h). WriteMtzReflections is exactly WriteMergedMtz of this.
MergedReflectionsMessage MergedReflectionsForWriter(const std::vector<MergedReflection> &reflections,
                                                    const UnitCell &unitCell,
                                                    const DiffractionExperiment &experiment,
                                                    const OutputProvenance &provenance);

void WriteMtzReflections(const std::vector<MergedReflection> &reflections,
                         const UnitCell &unitCell,
                         const DiffractionExperiment &experiment,
                         const OutputProvenance &provenance,
                         const std::string &filename);

// SHELX HKLF-4 text file, FORMAT(3I4,2F8.2) h k l I sigma(I), scaled so the largest value fits the
// field, ended by a 0 0 0 record. nthreads: workers for the row formatting, as for the mmCIF.
// Merged reflections, Bijvoet mates as separate records (the stills output).
void WriteShelxHklReflections(const std::vector<MergedReflection> &reflections,
                              const DiffractionExperiment &experiment,
                              const std::string &filename,
                              size_t nthreads);
// Unmerged scaled fulls, one record each at its measured index (the rotation output).
void WriteShelxHklReflections(const std::vector<ScaledFull> &fulls,
                              const std::string &filename,
                              size_t nthreads);

// Unmerged observations in the column and batch-header layout POINTLESS writes: aimless, pointless,
// careless and iotbx.merging_statistics all read that layout. H K L are the ASU indices and M/ISYM
// recovers the index the reflection was measured at (which is what careless needs to see the crystal
// frame) and says whether the observation is a partial.
// sum_partials: add the partials of each rocking event into one full, written at the batch of the
// event's centroid with the summed rocking-curve fraction in FRACTIONCALC - the plain sum every
// rotation program writes, over the events the combine would assemble (--min-partiality). False
// writes one row per integrated box instead, flagged as partials for the reading program to sum.
// Stills have no rocking events and are unaffected either way.
// The intensities carry the deterministic per-reflection corrections and nothing else - Lorentz
// and polarization in LP, the sensor's angle-dependent efficiency in QE, and the attenuation of the
// flight-path medium in FLIGHT - so raw counts are I / LP * QE * FLIGHT. The partiality and the
// per-image scale are left for the reading program to fit, since every program this file is for
// fits a scale model of its own.
void WriteUnmergedMtzReflections(const std::vector<IntegrationOutcome> &outcomes,
                                 const UnitCell &unitCell,
                                 const DiffractionExperiment &experiment,
                                 bool sum_partials,
                                 const OutputProvenance &provenance,
                                 const std::string &filename,
                                 size_t nthreads = 1);

// The same file in two steps, for a caller that builds it while the outcomes' per-image scale fields
// are still being written: UnmergedMtz reads everything but mosaicity_deg, which
// SetUnmergedMtzMosaicity then copies into the batch headers. The Mtz points at the experiment's space
// group, so the experiment has to outlive it.
gemmi::Mtz UnmergedMtz(const std::vector<IntegrationOutcome> &outcomes,
                       const UnitCell &unitCell,
                       const DiffractionExperiment &experiment,
                       bool sum_partials,
                       const OutputProvenance &provenance,
                       size_t nthreads = 1);
void SetUnmergedMtzMosaicity(gemmi::Mtz &mtz, const std::vector<IntegrationOutcome> &outcomes);

void WriteReflections(const std::vector<MergedReflection> &reflections,
                         const UnitCell &unitCell,
                         const DiffractionExperiment &experiment,
                         const MergeStatistics &statistics,
                         const ErrorModelReport &error_model,
                         const TwinningAnalysisResult &twinning,
                         const OutputProvenance &provenance,
                         const std::string &filename,
                         size_t nthreads,
                         const std::vector<ScaledFull> *scaled_fulls = nullptr);