From cfc54709e598e4d025f5a40d55b48c74c25a0803 Mon Sep 17 00:00:00 2001
From: Filip Leonarski <filip.leonarski@psi.ch>
Date: Thu, 5 Nov 2026 15:21:47 +0100
Subject: [PATCH] Refinement report: REFINE_SCORE_* describe the refined model

REFINE_SCORE_R_WORK, REFINE_SCORE_R_FREE and every other REFINE_SCORE_
term were taken from RefinementResult::score_start, the score of the
model as given, and the geometry terms from geometry_start. After a
refinement the report therefore carried the starting R-work under a name
that reads as the result, beside a different, lower REFINE_R_WORK and
the CLI's "refined: R-work ..." line.

The refinement now scores the model it ends with when it makes its maps
(RefinementResult::score), and the REFINE_SCORE_ terms are that score,
with the final geometry where the restrained stage ran:
REFINE_SCORE_R_WORK/R_FREE equal REFINE_R_WORK/R_FREE and the CLI's
numbers. Where the model is only scored (--refine-score-only) it is the
model as given, so refine_parity.py reads the same values as before.
The starting values stay under their own names (REFINE_R_WORK_START,
REFINE_R_FREE_START, REFINE_RMSD_*_START). The neighbouring keys were
checked: the bulk solvent, the geometry and the R-factors other than
these were already the final model's.

9t6s (open arm): REFINE_SCORE_R_WORK/R_FREE 0.2790/0.2904 (= START)
before, 0.2798/0.2994 (= REFINE_R_WORK/R_FREE) after. 1exr (refine arm,
--mode refine): 0.1253/0.1320 before, 0.1271/0.1377 after; with
--refine-score-only every REFINE_SCORE_ line is identical before and
after.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UqXYdL4qBGYRiSXSGXfCLu
---
 docs/CPU_DATA_ANALYSIS_REFINEMENT.md          |  2 +-
 docs/RUGNUX_REPORT.md                         |  4 ++--
 .../structure_refinement/Refinement.cpp       |  1 +
 .../structure_refinement/Refinement.h         |  3 +++
 rugnux/ResultReport.cpp                       | 19 +++++++++++--------
 5 files changed, 18 insertions(+), 11 deletions(-)

diff --git a/docs/CPU_DATA_ANALYSIS_REFINEMENT.md b/docs/CPU_DATA_ANALYSIS_REFINEMENT.md
index b136b6ed0..1ba5dfde6 100644
--- a/docs/CPU_DATA_ANALYSIS_REFINEMENT.md
+++ b/docs/CPU_DATA_ANALYSIS_REFINEMENT.md
@@ -503,7 +503,7 @@ higher, one 0.0016 lower). `--refine-score-only` builds nothing, and the build a
 `REFINE_SOLVENT_ADDED` and `REFINE_SOLVENT_REMOVED` count the waters added and still there and those of the model
 as given taken out, `REFINE_SOLVENT_RELABELLED` the sites relabelled (each, with its scores, in the report and the
 JSON); `REFINE_SOLVENT_NOT_SOLVENT` the not-solvent peaks of the final model's difference map;
-`REFINE_SOLVENT_BUILD_ROUNDS` the rounds kept. The model as given (`REFINE_R_FREE_START`, the `REFINE_SCORE_` terms) and the placement stage are the first refinement's; the refined model, its R-factors, geometry, maps and blobs are the last kept round's.
+`REFINE_SOLVENT_BUILD_ROUNDS` the rounds kept. The model as given (`REFINE_R_FREE_START`) and the placement stage are the first refinement's; the refined model, its R-factors (the `REFINE_SCORE_` terms with them), geometry, maps and blobs are the last kept round's.
 
 ### 15.11 GPU and CPU
 
diff --git a/docs/RUGNUX_REPORT.md b/docs/RUGNUX_REPORT.md
index cfd26fe5a..10d67648a 100644
--- a/docs/RUGNUX_REPORT.md
+++ b/docs/RUGNUX_REPORT.md
@@ -1453,7 +1453,7 @@ build ran, a `build` object follows: `rounds`, `added`, `removed`, `not_solvent`
 model: `kind` (`ADDED`, `REMOVED`, `NOT_SOLVENT`), `round`, `site` (the water's name, empty for a peak),
 `xyz`, `difference_sigma`, `map_sigma`, `b_iso`, `elongation` and `reason`.
 
-**The score of the model as given** follows, every term under `REFINE_SCORE_`: `REFINE_SCORE_R_WORK`,
+**The score of the refined model** follows - the model written out, so `REFINE_SCORE_R_WORK` and `REFINE_SCORE_R_FREE` are `REFINE_R_WORK` and `REFINE_R_FREE` (where the model was only scored, the model as given; `REFINE_R_WORK_START` and `REFINE_RMSD_BONDS_START` are where a refinement began) - every term under `REFINE_SCORE_`: `REFINE_SCORE_R_WORK`,
 `REFINE_SCORE_R_FREE`, `REFINE_SCORE_N_WORK` and `REFINE_SCORE_N_FREE` by default, and with `--developer` the
 overall scale (`REFINE_SCORE_K_OVERALL`), its isotropic and anisotropic B (`REFINE_SCORE_B_ISO`,
 `REFINE_SCORE_B_ANISO`: B11 B22 B33 B12 B13 B23 less the isotropic part, Cartesian), the bulk solvent
@@ -1463,7 +1463,7 @@ riding hydrogens (`REFINE_SCORE_HYDROGENS`), the likelihood over the working and
 (`REFINE_SCORE_FOM`), the geometry's rmsd and rmsZ (`REFINE_SCORE_RMSD_BONDS`, `REFINE_SCORE_RMSZ_BONDS`,
 `REFINE_SCORE_RMSD_ANGLES`, `REFINE_SCORE_RMSZ_ANGLES`, `REFINE_SCORE_RMSD_METAL_BONDS`,
 `REFINE_SCORE_RMSD_BONDS_ALL` for covalent and metal bonds together) and a table of R-work and R-free in 20
-resolution shells. `rugnux --mode refine --refine-score-only` writes this score and nothing else.
+resolution shells. `rugnux --mode refine --refine-score-only` writes this score, of the model as given, and nothing else.
 
 In `--mode refine` the input's keys come first: `REFINE_REFLECTIONS` and `REFINE_FREE_REFLECTIONS` (those read,
 after any `--refine-d-min`), `REFINE_FRENCH_WILSON` (`TRUE` where the file had intensities only and the amplitudes
diff --git a/image_analysis/structure_refinement/Refinement.cpp b/image_analysis/structure_refinement/Refinement.cpp
index e2449d33a..793e12425 100644
--- a/image_analysis/structure_refinement/Refinement.cpp
+++ b/image_analysis/structure_refinement/Refinement.cpp
@@ -2294,6 +2294,7 @@ RefinementResult RefineOnce(const gemmi::Structure &placed, const std::vector<Me
     // The maps, the blobs and the model of where the refinement ended.
     auto finish = [&]() {
         MakeMaps(ctx, merged, wavelength_A, result);
+        result.score = ctx.Score();   // at the scale and solvent MakeMaps refitted
         if (ctx.refl.Twinned()) {
             result.twin_fraction = FractionSum(ctx.rows);
             result.twin_multi_domains = DomainText(ctx.refl, ctx.rows);
diff --git a/image_analysis/structure_refinement/Refinement.h b/image_analysis/structure_refinement/Refinement.h
index 909ccfb13..c10e6dd84 100644
--- a/image_analysis/structure_refinement/Refinement.h
+++ b/image_analysis/structure_refinement/Refinement.h
@@ -154,6 +154,9 @@ struct RefinementResult {
     // where the restrained stage runs or the model is only scored), and every term of that score.
     double r_work_start = 1, r_free_start = 1;
     RefinementScore score_start;
+    // Every term of the score of the model the refinement ended with (the one written out), as its maps are made:
+    // the model as given where it was only scored.
+    RefinementScore score;
     // How the model's displacements were read: "isotropic", "ANISOU" (the atoms' own U), or "TLS, B total" / "TLS, B
     // residual" (U from the model's TLS groups, its B column taken as the total B or as the residual to them) - the
     // reading of the TLS groups the model's own R-free chose among these and the isotropic B.
diff --git a/rugnux/ResultReport.cpp b/rugnux/ResultReport.cpp
index 8d8759344..7e67df00b 100644
--- a/rugnux/ResultReport.cpp
+++ b/rugnux/ResultReport.cpp
@@ -574,7 +574,7 @@ namespace {
     }
 
     // The refinement's keys (Refinement.h): REFINE_ of the refinement of a placed model and of --mode refine, with every term of the
-    // score of the model as given under REFINE_SCORE_.
+    // score of the refined model under REFINE_SCORE_.
     void AddRefinementKeys(ReportSection &s, const RefinementResult &rf, const std::string &output_prefix) {
         Add(s, Blank());
         if (!rf.ok) {
@@ -689,7 +689,10 @@ namespace {
                 Add(s, KeyEnum("REFINE_SOLVENT", "NOT_PERFORMED", {"PERFORMED", "NOT_PERFORMED"}));
         }
         if (rf.ok) {
-            const RefinementScore &sc = rf.score_start;
+            // the model the refinement ended with, as REFINE_R_WORK/REFINE_R_FREE (the model as given where it was
+            // only scored: REFINE_R_WORK_START and REFINE_RMSD_BONDS_START say where it began)
+            const RefinementScore &sc = rf.score;
+            const GeometryStatistics &geometry = rf.restrained ? rf.geometry : rf.geometry_start;
             Add(s, KeyReal("REFINE_SCORE_R_WORK", sc.r_work, "{:.4f}"));
             Add(s, KeyReal("REFINE_SCORE_R_FREE", sc.r_free, "{:.4f}"));
             Add(s, KeyInt("REFINE_SCORE_N_WORK", sc.n_work));
@@ -706,12 +709,12 @@ namespace {
             Add(s, KeyReal("REFINE_SCORE_NLL_WORK", sc.nll_work, "{:.1f}", true));
             Add(s, KeyReal("REFINE_SCORE_NLL_FREE", sc.nll_free, "{:.1f}", true));
             Add(s, KeyReal("REFINE_SCORE_FOM", sc.fom, "{:.4f}", true));
-            Add(s, KeyReal("REFINE_SCORE_RMSD_BONDS", rf.geometry_start.rmsd_bonds, "{:.4f}", true));
-            Add(s, KeyReal("REFINE_SCORE_RMSZ_BONDS", rf.geometry_start.rmsz_bonds, "{:.3f}", true));
-            Add(s, KeyReal("REFINE_SCORE_RMSD_METAL_BONDS", rf.geometry_start.rmsd_metal, "{:.4f}", true));
-            Add(s, KeyReal("REFINE_SCORE_RMSD_BONDS_ALL", rf.geometry_start.RmsdAllBonds(), "{:.4f}", true));
-            Add(s, KeyReal("REFINE_SCORE_RMSD_ANGLES", rf.geometry_start.rmsd_angles, "{:.3f}", true));
-            Add(s, KeyReal("REFINE_SCORE_RMSZ_ANGLES", rf.geometry_start.rmsz_angles, "{:.3f}", true));
+            Add(s, KeyReal("REFINE_SCORE_RMSD_BONDS", geometry.rmsd_bonds, "{:.4f}", true));
+            Add(s, KeyReal("REFINE_SCORE_RMSZ_BONDS", geometry.rmsz_bonds, "{:.3f}", true));
+            Add(s, KeyReal("REFINE_SCORE_RMSD_METAL_BONDS", geometry.rmsd_metal, "{:.4f}", true));
+            Add(s, KeyReal("REFINE_SCORE_RMSD_BONDS_ALL", geometry.RmsdAllBonds(), "{:.4f}", true));
+            Add(s, KeyReal("REFINE_SCORE_RMSD_ANGLES", geometry.rmsd_angles, "{:.3f}", true));
+            Add(s, KeyReal("REFINE_SCORE_RMSZ_ANGLES", geometry.rmsz_angles, "{:.3f}", true));
             if (!sc.shells.empty()) {
                 ReportEntry e;
                 e.kind = ReportEntry::Kind::Table;