v1.0.0-rc.160 (#70)

This is an UNSTABLE release. It includes many experimental features, as well as many AI generated fixes. We recommend using rc.152 for production use.

* rugnux: Add `--model model.pdb` - score the merged data against an atomic model and compute initial maps. It reports R-work/R-free (scaling the model to the observed amplitudes with an overall scale, an anisotropic B and a flat bulk solvent - the standard few-parameter model, so a batch of maps stays directly comparable) and writes 2Fo-Fc / Fo-Fc electron-density maps (CCP4) plus a map-coefficient MTZ. The structure itself is not refined; the model is only re-fractionalised into the data cell.
* rugnux: The merged reflection output now carries French-Wilson amplitudes (|F| and its sigma) next to the intensities - MTZ `F`/`SIGF`, mmCIF `_refln.F_meas_au`, and the text HKL - computed with the correct centric/acentric Wilson prior and epsilon multiplicity, so a downstream program (e.g. phenix.refine) can refine against amplitudes. The intensity columns are unchanged.
* rugnux: R-free test-set flags are now assigned deterministically and consistently across symmetry - a Bijvoet pair I(+)/I(-) is never split between the work and free sets, and the assignment is a reproducible per-hkl hash that depends only on the reflection index, so every dataset of one crystal form gets the same ~5% free set (what a multi-dataset campaign such as PanDDA needs). On small data the fraction is floored so the test set stays large enough for a stable R-free (~500 reflections, capped at 10%); it stays flat at 5% on ordinary data. When a reference MTZ carries a `FreeR_flag` column its test set is imported instead, letting a whole campaign inherit one shared free set.
* rugnux: A reference MTZ (`--reference-mtz`) can now fix the space group and cell for rotation data too (previously rejected), without being used to scale - the rotation merge stays self-consistent. When the crystal has an indexing (merohedral) ambiguity - a lattice symmetry higher than its Laue symmetry, e.g. P3/P4/P6/C2 - the reference also resolves it: each candidate reindexing (identity plus the twin-law cosets of the metric symmetry) is scored by its intensity correlation against the reference and the data are re-merged in the best-correlating one. This is a metric-preserving relabelling of hkl (the cell is unchanged) and a no-op for a holohedral crystal such as lysozyme.
* rugnux: `--model` validation now aligns the data to the model before scoring - the observed reflections are reindexed into the model's enantiomorph when the two differ only by hand (indistinguishable from merged intensities). A merohedral indexing ambiguity is resolved against the reference MTZ when one is given (so a whole campaign shares one indexing convention); only with a model and no reference does validation fall back to fitting each candidate reindexing and keeping the lowest R-free.
* rugnux: De-novo symmetry - recover a genuine high-symmetry group whose data are imperfectly scaled. Such a merge's within-orbit chi² lands just past the self-consistency bound (each real symmetry step adds a little systematic scatter), right where a merohedral twin also lands, so the chi² ratio alone cannot separate them. The candidate is now rescued when the extra intensity-proportional systematic error it invokes stays small relative to the confirmed subgroup - a genuine symmetry step gains multiplicity without inflating the merge error model's b, whereas a twin forces non-equivalent reflections together and b balloons. Fixes cubic insulin (I23 instead of I222) with no change to any other crystal in the test battery, including the twins that must stay in their lower symmetry.
* Docs: Document the French-Wilson amplitude estimation, R-free flagging, reference-based space-group/ambiguity resolution, and model-based validation/maps in CPU_DATA_ANALYSIS.md.
* Frontend: The status-bar pill now shows a progress bar during detector calibration (previously only during measurement), and the calibration state and its button are labelled "Calibration"/"CALIBRATE" (the internal `Pedestal` state name is unchanged for back-compatibility).Reviewed-on: #70

Co-authored-by: Filip Leonarski <filip.leonarski@psi.ch>

image_analysis/IndexAndRefine.cpp

@@ -10,6 +10,7 @@
 #include "indexing/FFTIndexer.h"
 #include "indexing/MultiLatticeSearch.h"
 #include "lattice_search/LatticeSearch.h"
+#include "scale_merge/ReindexAmbiguity.h"
 #include "scale_merge/ScaleOnTheFly.h"
 
 IndexAndRefine::IndexAndRefine(const DiffractionExperiment &x, IndexerThreadPool *indexer, bool retain_outcomes)
@@ -176,6 +177,23 @@ IndexAndRefine::IndexingOutcome IndexAndRefine::DetermineLatticeAndSymmetry(Data
     return outcome;
 }
 
+namespace {
+// Count spots whose fractional Miller index falls within the indexing tolerance of an integer for a
+// given lattice + geometry - the "how well does this model explain the spots" score used by -r multi.
+int CountIndexedSpots(const DiffractionGeometry &geom, const CrystalLattice &latt,
+                      const std::vector<SpotToSave> &spots, float tol_sq) {
+    const Coord a = latt.Vec0(), b = latt.Vec1(), c = latt.Vec2();
+    int n = 0;
+    for (const auto &s : spots) {
+        const Coord recip = s.ReciprocalCoord(geom);
+        const float hf = recip * a, kf = recip * b, lf = recip * c;
+        const float dh = hf - std::round(hf), dk = kf - std::round(kf), dl = lf - std::round(lf);
+        if (dh * dh + dk * dk + dl * dl < tol_sq) ++n;
+    }
+    return n;
+}
+}   // namespace
+
 void IndexAndRefine::RefineGeometryIfNeeded(DataMessage &msg, IndexAndRefine::IndexingOutcome &outcome) {
     if (!outcome.lattice_candidate)
         return;
@@ -187,6 +205,11 @@ void IndexAndRefine::RefineGeometryIfNeeded(DataMessage &msg, IndexAndRefine::In
         .latt = *outcome.lattice_candidate,
         .crystal_system = outcome.symmetry.crystal_system,
         .min_spots = experiment.GetIndexingSettings().GetViableCellMinSpots(),
+        // Match the [30,150] deg bound the indexers already use (FFBIDXIndexer, FFT settings):
+        // the struct default [60,120] clamps a monoclinic beta outside that window (e.g. a C2
+        // beta near 132 deg) to the boundary, corrupting the per-frame cell refinement.
+        .min_angle_deg = 30.0f,
+        .max_angle_deg = 150.0f,
         .refine_beam_center = true,
         .refine_distance_mm = false,
         .refine_detector_angles = false,
@@ -213,6 +236,39 @@ void IndexAndRefine::RefineGeometryIfNeeded(DataMessage &msg, IndexAndRefine::In
                 outcome.beam_center_updated = true;
             }
             break;
+        case GeomRefinementAlgorithmEnum::Flex: {
+            // Try all three refinements per image and keep whichever indexes the most spots. Beam+cell
+            // refinement helps some stills but diverges on sparse spot lists (few spots, long axes),
+            // where it pushes a good lattice out of tolerance; scoring by indexed-spot count lets each
+            // image fall back to orientation-only or no refinement when refinement would hurt. Ties
+            // prefer less refinement (strict >, not >=) to avoid overfitting.
+            const float tol = experiment.GetIndexingSettings().GetTolerance();
+            const float tol_sq = tol * tol;
+
+            XtalOptimizerData d_none = data;
+            XtalOptimizerData d_orient = data;
+            XtalOptimizerRotationOnly(d_orient, msg.spots, 0.2);
+            XtalOptimizerRotationOnly(d_orient, msg.spots, 0.1);
+            XtalOptimizerRotationOnly(d_orient, msg.spots, 0.05);
+            XtalOptimizerData d_beam = data;
+            const bool beam_ok = XtalOptimizer(d_beam, {msg.spots});
+
+            const int s_none = CountIndexedSpots(d_none.geom, d_none.latt, msg.spots, tol_sq);
+            const int s_orient = CountIndexedSpots(d_orient.geom, d_orient.latt, msg.spots, tol_sq);
+            const int s_beam = beam_ok ? CountIndexedSpots(d_beam.geom, d_beam.latt, msg.spots, tol_sq) : -1;
+
+            if (s_beam > s_none && s_beam > s_orient) {
+                data = d_beam;
+                outcome.experiment.BeamX_pxl(data.geom.GetBeamX_pxl())
+                        .BeamY_pxl(data.geom.GetBeamY_pxl());
+                outcome.beam_center_updated = true;
+            } else if (s_orient > s_none) {
+                data = d_orient;
+            } else {
+                data = d_none;
+            }
+            break;
+        }
     }
 
     outcome.lattice_candidate = data.latt;
@@ -302,6 +358,16 @@ void IndexAndRefine::QuickPredictAndIntegrate(DataMessage &msg,
             mos_deg = msg.mosaicity_deg.value();
             mosaicity[msg.number] = mos_deg;
         }
+        // Second pass of the rotation two-pass: widen the prediction to the frame-order-smoothed mosaicity
+        // that RotationScaleMerge fitted in the first pass. Take the MAX with this frame's own estimate so
+        // prediction is never NARROWER than the first pass - a too-narrow smoothed value would otherwise drop
+        // reflections and collapse the multiplicity. (A wider value only helps prediction cover the spot.)
+        if (msg.number >= 0 && msg.number < static_cast<int64_t>(prediction_mosaicity_override_.size())
+            && std::isfinite(prediction_mosaicity_override_[msg.number])
+            && prediction_mosaicity_override_[msg.number] > 0.0f) {
+            mos_deg = std::max(mos_deg, prediction_mosaicity_override_[msg.number]);
+            mosaicity[msg.number] = mos_deg;
+        }
     }
 
     IntegrationOutcome i_outcome{
@@ -324,7 +390,11 @@ void IndexAndRefine::QuickPredictAndIntegrate(DataMessage &msg,
         .wedge_deg = std::fabs(wedge_deg),
         .mosaicity_deg = std::fabs(mos_deg),
         // FWHM -> sigma; 0 when monochromatic, leaving the prediction unchanged.
-        .bandwidth_sigma = experiment.GetBandwidthFWHM().value_or(0.0f) / 2.3548f
+        .bandwidth_sigma = experiment.GetBandwidthFWHM().value_or(0.0f) / 2.3548f,
+        // Experimental stills partiality (off by default): sigma = ewald_dist_cutoff/2 = the per-image
+        // profile radius, so a reflection at the acceptance edge (dist_ewald ~ 2*sigma) keeps p ~ exp(-2).
+        .still_partiality = experiment.GetBraggIntegrationSettings().GetStillPartiality(),
+        .profile_radius_recipA = ewald_dist_cutoff * 0.5f
     };
 
     // Predict, then integrate with the selected integrator (box-sum or profile-fit).
@@ -431,23 +501,29 @@ std::optional<RotationIndexerResult> IndexAndRefine::FinalizeRotationIndexing()
 }
 
 IndexAndRefine &IndexAndRefine::ReferenceIntensities(std::vector<MergedReflection> &reference) {
-    scaling_engine = std::make_unique<ScaleOnTheFly>(experiment, reference);
+    // An external reference is trusted to be in the correct hand, so use it to break the merohedral
+    // indexing ambiguity per image (serial stills index each crystal independently).
+    reindex_resolver = std::make_unique<ReindexAmbiguityResolver>(experiment, reference);
     return *this;
 }
 
 void IndexAndRefine::ScaleImage(DataMessage &msg, IntegrationOutcome& outcome) {
-    if (!scaling_engine)
+    if (!reindex_resolver)
+        return;
+
+    // The external reference fixes the cell/space group, breaks the indexing ambiguity and reports CCref,
+    // but is NEVER a scale anchor: scaling an image against a foreign dataset injects cross-dataset
+    // systematics and is a worse reference than the data's own merge, so scaling self-references at the
+    // post-measurement merge for both workflows. Rotation resolves the ambiguity globally and self-scales
+    // in RotationScaleMerge (ChooseReindex / ReferenceIntensityCC), so there is nothing to do per image.
+    // Stills resolve the merohedral ambiguity per image here (each crystal indexes in a random hand; pick
+    // the hand best-correlated with the reference, once and for good).
+    if (experiment.IsRotationIndexing())
         return;
 
     auto scaling_start_time = std::chrono::steady_clock::now();
-    scaling_engine->Scale(outcome);
+    reindex_resolver->Resolve(outcome.reflections);
     auto scaling_end_time = std::chrono::steady_clock::now();
-
-    scale_cc[msg.number] = outcome.image_scale_cc.value_or(NAN);
-    msg.image_scale_b_factor = outcome.image_scale_b_factor_Ang2;
-    msg.image_scale_factor = outcome.image_scale_g;
-    msg.image_scale_mosaicity = outcome.mosaicity_deg;
-    msg.image_scale_cc = outcome.image_scale_cc;
     msg.image_scale_time_s = std::chrono::duration<float>(scaling_end_time - scaling_start_time).count();
 }