// SPDX-FileCopyrightText: 2026 Filip Leonarski, Paul Scherrer Institute // SPDX-License-Identifier: GPL-3.0-only #pragma once #include #include "../common/DiffractionExperiment.h" #include "../common/Logger.h" #include "ReportDocument.h" #include "Rugnux.h" // _report.txt - what the run DETERMINED, written next to the .mtz/.cif/.hkl on every run // that has an output prefix. Modelled on XDS's CORRECT.LP: prose and tables a crystallographer // reads top to bottom, with `KEY= value` assignment lines and fixed-width tables a script greps // without parsing prose. Rates and per-image progress are deliberately absent - those are stdout; // the command line and the total wall time are here, because they say how this result was produced // and a report that has to be read next to a lost shell history is worth less. // // The format is an interface: key names, table columns and the reason vocabulary are stable, and // REPORT_VERSION is bumped if they ever change. See docs/RUGNUX_REPORT.md. // How the run was produced: the invocation, what it cost, and what it ran on. The CLI is the only // caller that knows these, so they are passed in rather than read here. Each is left out of the // report when it is not given - a caller that cannot supply one must not have the report claim the // run was invoked by nobody, took no time, or saw no GPU. struct RunProvenance { std::string command_line; // argv as one shell-ready line double wall_time_s = 0.0; // the whole invocation; 0 = not measured int32_t gpu_count = -1; // -1 = not reported; 0 is a statement, not an omission std::string gpu_description; // "4x NVIDIA A100-SXM4-80GB"; empty when there is no GPU // --developer: render the pipeline internals and the long explanations as well. The document is // built the same either way; this only selects how much of it the text rendering prints. bool developer = false; }; // Authorship, licence and terms of use, written at the head of every report. The facts are the // repository's: the copyright headers name the author, LICENSE is GPLv3, and the sentence about // academic and commercial use restates what that licence already grants - said here because a // report travels to readers who will never open a licence file. inline constexpr const char *RUGNUX_AUTHORSHIP = "rugnux is written by Filip Leonarski at the Paul Scherrer Institute.\n" "Copyright (C) 2019-2026 Paul Scherrer Institute. It is free software under the\n" "GNU General Public License v3 (see the LICENSE file): academic institutions and\n" "commercial companies alike are free to use it.\n" "Releases: https://gitea.psi.ch/mx/Jungfraujoch/releases"; // The acknowledgement, printed by the CLI at startup and at the head of every report, so a // result carries it wherever it travels. The methods are the field's, not this program's, and the // program stands on other people's open-source code; the files named here are installed beside the // binary (share/doc/jfjoch_rugnux on Linux, next to rugnux.exe in the Windows archive). inline constexpr const char *RUGNUX_ACKNOWLEDGEMENT = "The methods rugnux implements were developed and published by the X-ray research\n" "community, and the program is built on open-source software from many projects. Both\n" "are credited in ACKNOWLEDGEMENT.md, with the licence terms in LICENSE and\n" "THIRD_PARTY_NOTICES.md - all three ship with this package."; // The emitter. Populates the result object every rendering reads from; it writes no text itself. ReportDocument BuildReportDocument(const std::string &output_prefix, const std::string &input_file, const DiffractionExperiment &experiment, const ProcessResult &result, const RunProvenance &provenance = {}); // The text rendering of that document - XDS-style prose, tables and `KEY= value` lines. Reads only // from the document, so a second rendering is a second function of the same input. std::string RenderReportText(const ReportDocument &doc, bool developer); // Renders the report. Exposed for testing; RunPipeline results are the only input. std::string RenderResultReport(const std::string &output_prefix, const std::string &input_file, const DiffractionExperiment &experiment, const ProcessResult &result, const RunProvenance &provenance = {});