From 004839a8ee16b07fc91448e05e1f0a8e2434b08c Mon Sep 17 00:00:00 2001 From: Filip Leonarski Date: Sat, 19 Sep 2026 23:58:50 +0200 Subject: [PATCH] Space-group search: the twin-immune zone arbitrates a refused promotion A promotion the operator correlations confirm and a gate refuses (the H ratio, the added-operator R, the merge chi^2) used to be settled two ways that both read the per-frame scales: the two-arm rule let the other arm's confirmation outvote the refusal, and the remerge arbiter compared the R_meas and ISa of the two pinned merges. Neither holds once the scales have settled: a partial twin at a fraction one arm's coverage hides passes there (an H3 twin promoted to R32, a P31 one to P3121), and the lower group's converged merge - the same scales fitted against fewer equivalents - agrees with itself better than the true group on a genuine step (a 2 -> 222 step reading R_meas 0.094 -> 0.103), so the arbiter refuses real symmetry. The refusal is now decided by the twin-immune zone of the operators the promotion adds: the reflections centric in the higher group and acentric in the lower are their own twin mates, so they read centric if the operators are real and acentric if they are a twin law or a pseudo-symmetry, whatever the twin fraction and however the scales were fitted. Read on the all-observation P1 merge in the two-arm rule and on the adopted group's own merge at the arbiter (where a weak crystal's P1 search merge has no shell with signal to read), for a group two orders above the other, with the pseudo-translation normalisation the L-test uses, and decided on the sign with the screw-axis convention of 20 nats: acentric and the refusal stands on all observations, centric and the higher group is adopted, undecided and the rules stay as they were. Measured: a genuine 222 step reads +150 to +1630 nats, the trigonal twins -130 nats and below. A refusal that stood on the zone names the law: the first operator the refused group adds, at the fraction the operator's own H implies (else the pre-search L-test), reported as TWIN_LAW and written as the mmCIF _pdbx_reflns_twin loop of the merge in the true group. Every lattice twin law outside the adopted group is reported with its own H, implied fraction, R and correlation on the merge expanded to P1 (TWIN_LAW_n), following Yeates (1997) Methods Enzymol. 276, 344-358. Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_013nW6FNRP1bBJJ8pfHiByAT --- image_analysis/WriteReflections.cpp | 17 ++ .../scale_merge/SearchSpaceGroup.cpp | 7 + image_analysis/scale_merge/SearchSpaceGroup.h | 5 + .../scale_merge/TwinningAnalysis.cpp | 171 ++++++++++------ image_analysis/scale_merge/TwinningAnalysis.h | 14 ++ rugnux/ResultReport.cpp | 17 ++ rugnux/Rugnux.cpp | 193 +++++++++++++++++- rugnux/Rugnux.h | 6 + 8 files changed, 366 insertions(+), 64 deletions(-) diff --git a/image_analysis/WriteReflections.cpp b/image_analysis/WriteReflections.cpp index 2a7b6a4c4..ab9453d33 100644 --- a/image_analysis/WriteReflections.cpp +++ b/image_analysis/WriteReflections.cpp @@ -272,6 +272,23 @@ void WriteMmcifReflections(const std::vector &reflections, if (twinning.moment_reflections > 0) out << "_reflns.jfjoch_second_moment_I " << Fmt(twinning.second_moment, 3) << " # /^2 (untwinned 2.00, perfect twin 1.50)\n"; + // A twin law the run identified (TwinningAnalysisResult::twin_law_operator): the standard + // PDBx loop, one row per domain, the second domain related by the operator. Only meaningful + // in the true (sub)group's file, which is the one this is - in the higher group the operator + // is a symmetry element. Merohedral: the law is a lattice operation of the crystal system. + if (!twinning.twin_law_operator.empty()) { + out << "#\n"; + out << "loop_\n"; + out << "_pdbx_reflns_twin.domain_id\n"; + out << "_pdbx_reflns_twin.crystal_id\n"; + out << "_pdbx_reflns_twin.diffrn_id\n"; + out << "_pdbx_reflns_twin.operator\n"; + out << "_pdbx_reflns_twin.fraction\n"; + out << "_pdbx_reflns_twin.type\n"; + out << "1 1 1 'h,k,l' " << Fmt(1.0 - twinning.twin_law_fraction, 3) << " merohedral\n"; + out << "2 1 1 " << CifStr(twinning.twin_law_operator) << " " << Fmt(twinning.twin_law_fraction, 3) + << " merohedral\n"; + } // Radiation-damage monitor (rotation): the relative Debye-Waller B change from the first to the last // frame (A^2). A large magnitude flags a dose-dependent resolution-scale change = radiation damage; // positive is the typical direction (high-resolution intensity fades with dose). No standard mmCIF item. diff --git a/image_analysis/scale_merge/SearchSpaceGroup.cpp b/image_analysis/scale_merge/SearchSpaceGroup.cpp index d220ae05c..3de94bdc8 100644 --- a/image_analysis/scale_merge/SearchSpaceGroup.cpp +++ b/image_analysis/scale_merge/SearchSpaceGroup.cpp @@ -1297,6 +1297,8 @@ SearchSpaceGroupResult SearchSpaceGroup( bool closure = false; std::string why; }; int refused_order = 0; + bool refused_twin_gate = false; + double refused_fraction = std::numeric_limits::quiet_NaN(); std::string refused_pg_hm, refused_why; const gemmi::SpaceGroup *refused_pg_rep = nullptr; std::vector pg_cands; @@ -1579,6 +1581,9 @@ SearchSpaceGroupResult SearchSpaceGroup( refused_order = c.order; refused_pg_hm = c.pg->representative->point_group_hm(); refused_pg_rep = c.pg->representative; + refused_twin_gate = h_refused || r_refused; + refused_fraction = h_refused ? std::max(0.0, 0.5 - h_added) + : std::numeric_limits::quiet_NaN(); if (h_refused) // Twinning by a fraction a scales every twin-related difference by (1-2a), and // |I1-I2|/(I1+I2) is uniform on [0,1] for untwinned Wilson intensities, so the @@ -1702,6 +1707,8 @@ SearchSpaceGroupResult SearchSpaceGroup( result.refused_point_group_hm = refused_pg_hm; result.refused_reason = refused_why; result.refused_point_group_representative = *refused_pg_rep; + result.refused_by_twin_gate = refused_twin_gate; + result.refused_twin_fraction = refused_fraction; } // --- Stage B: pick the space group within the point group --- diff --git a/image_analysis/scale_merge/SearchSpaceGroup.h b/image_analysis/scale_merge/SearchSpaceGroup.h index 6db1a2ed5..c9d291b04 100644 --- a/image_analysis/scale_merge/SearchSpaceGroup.h +++ b/image_analysis/scale_merge/SearchSpaceGroup.h @@ -689,6 +689,11 @@ struct SearchSpaceGroupResult { // Empty when nothing was refused. Surfaced to the user - a silent demotion is how a twin gets missed. std::string refused_point_group_hm; std::string refused_reason; + // Of the refused candidate: the twin fraction its added operators' own disagreement implies + // (0.5 - H, a lower bound; NaN where H was not measured) and whether the refusal came from a twin + // gate (the H ratio or the added-operator R) rather than from the merge chi^2. + double refused_twin_fraction = std::numeric_limits::quiet_NaN(); + bool refused_by_twin_gate = false; // The symmorphic representative of that group - the same thing point_group_representative is, and // for the same reason (a name cannot tell P321 from P312). It is what a caller hands back as // fixed_point_group to ask what merging under the refused group would give. Unset when nothing diff --git a/image_analysis/scale_merge/TwinningAnalysis.cpp b/image_analysis/scale_merge/TwinningAnalysis.cpp index 488470f84..0ed2afb25 100644 --- a/image_analysis/scale_merge/TwinningAnalysis.cpp +++ b/image_analysis/scale_merge/TwinningAnalysis.cpp @@ -565,6 +565,111 @@ namespace { } } +namespace { + // The rotations of a group, as gemmi Ops without translations (its symmorphic representative's + // proper operations). + std::vector ProperRotations(const gemmi::GroupOps& gops) { + std::vector rotations; + for (const auto& op : gops.derive_symmorphic().sym_ops) + if (op.det_rot() > 0) + rotations.push_back(gemmi::Op{op.rot, {0, 0, 0}, 'x'}); + return rotations; + } + + // The reflections a zone test can be read on: present in the group, general position, in the + // shells with signal enough (ZONE_MIN_SHELL_ISIG). Fills the resolution range read. + std::vector StrongReflections(const std::vector& p1_merged, + const gemmi::GroupOps& gops, + TwinImmuneZoneResult& result) { + std::vector usable; + for (const auto& r : p1_merged) { + const gemmi::Op::Miller h{{r.h, r.k, r.l}}; + if (UsableIntensity(r) && std::isfinite(r.sigma) && r.sigma > 0.0 + && !gops.is_systematically_absent(h) && gops.epsilon_factor_without_centering(h) == 1) + usable.push_back(&r); + } + // The shells with signal enough to read (ZONE_MIN_SHELL_ISIG), 20 equal in 1/d^2. + constexpr int n_shells = 20; + double min_s = std::numeric_limits::infinity(), max_s = 0.0; + for (const auto* r : usable) { + min_s = std::min(min_s, 1.0 / (r->d * r->d)); + max_s = std::max(max_s, 1.0 / (r->d * r->d)); + } + std::vector strong; + if (!(max_s > min_s)) + return strong; + auto shell_of = [&](const MergedReflection* r) { + const double t = (1.0 / (r->d * r->d) - min_s) / (max_s - min_s); + return std::min(n_shells - 1, std::max(0, static_cast(t * n_shells))); + }; + std::vector isig_sum(n_shells, 0.0); + std::vector isig_n(n_shells, 0); + for (const auto* r : usable) { + isig_sum[shell_of(r)] += r->I / r->sigma; + isig_n[shell_of(r)] += 1; + } + for (const auto* r : usable) { + const int b = shell_of(r); + if (isig_n[b] > 0 && isig_sum[b] / isig_n[b] >= ZONE_MIN_SHELL_ISIG) + strong.push_back(r); + } + result.d_max_A = 0.0; + result.d_min_A = std::numeric_limits::infinity(); + for (const auto* r : strong) { + result.d_max_A = std::max(result.d_max_A, r->d); + result.d_min_A = std::min(result.d_min_A, r->d); + } + return strong; + } + + // The zone of one subgroup hypothesis H (given by its rotations): the reflections centric in the + // group but not in H - the self-mates of the coset the group adds over H. + TwinImmuneZone ReadSubgroupZone(const std::vector& strong, + const gemmi::GroupOps& gops, const std::vector& rotations, + const std::vector& h_ops, + const std::array* tncs_vector) { + auto contains = [&](const std::vector& set, const gemmi::Op& op) { + return std::any_of(set.begin(), set.end(), [&](const gemmi::Op& o) { return o.rot == op.rot; }); + }; + std::vector zone; + for (const auto* r : strong) { + const gemmi::Op::Miller h{{r->h, r->k, r->l}}; + const gemmi::Op::Miller minus{{-gemmi::Op::DEN * r->h, -gemmi::Op::DEN * r->k, -gemmi::Op::DEN * r->l}}; + const bool centric_in_h = std::any_of(h_ops.begin(), h_ops.end(), [&](const gemmi::Op& op) { + return op.apply_to_hkl_without_division(h) == minus; + }); + if (gops.is_reflection_centric(h) && !centric_in_h) + zone.push_back(r); + } + TwinImmuneZone z = ReadZone(zone, tncs_vector); + for (const auto& op : rotations) + if (!contains(h_ops, op)) + z.operators += (z.operators.empty() ? "" : " ") + op.as_hkl().triplet(); + return z; + } +} + +TwinImmuneZoneResult AnalyzeTwinImmuneZone(const std::vector& p1_merged, + const gemmi::SpaceGroup& group, const gemmi::SpaceGroup& subgroup, + const std::array* tncs_vector) { + TwinImmuneZoneResult result; + result.tncs_normalised = tncs_vector != nullptr; + const gemmi::GroupOps gops = group.operations(); + const std::vector rotations = ProperRotations(gops); + const std::vector h_ops = ProperRotations(subgroup.operations()); + const auto strong = StrongReflections(p1_merged, gops, result); + if (strong.empty()) + return result; + std::vector control; + for (const auto* r : strong) + if (!gops.is_reflection_centric(gemmi::Op::Miller{{r->h, r->k, r->l}})) + control.push_back(r); + result.control = ReadZone(control, tncs_vector); + result.control.operators = "acentric"; + result.zones.push_back(ReadSubgroupZone(strong, gops, rotations, h_ops, tncs_vector)); + return result; +} + TwinImmuneZoneResult AnalyzeTwinImmuneZones(const std::vector& p1_merged, const gemmi::SpaceGroup& group, const std::array* tncs_vector) { @@ -592,10 +697,7 @@ TwinImmuneZoneResult AnalyzeTwinImmuneZones(const std::vector& ops.push_back(p); return ops; }; - std::vector rotations; - for (const auto& op : gops.derive_symmorphic().sym_ops) - if (op.det_rot() > 0) - rotations.push_back(gemmi::Op{op.rot, {0, 0, 0}, 'x'}); + const std::vector rotations = ProperRotations(gops); std::vector squares{gemmi::Op::identity()}; for (const auto& g : rotations) squares.push_back(g * g); @@ -619,49 +721,9 @@ TwinImmuneZoneResult AnalyzeTwinImmuneZones(const std::vector& if (subgroups.empty()) return result; - // Reflections present in the group and in general position (epsilon 1): an axial row is fixed by - // more than one operator and follows neither distribution. - std::vector usable; - for (const auto& r : p1_merged) { - const gemmi::Op::Miller h{{r.h, r.k, r.l}}; - if (UsableIntensity(r) && std::isfinite(r.sigma) && r.sigma > 0.0 - && !gops.is_systematically_absent(h) && gops.epsilon_factor_without_centering(h) == 1) - usable.push_back(&r); - } - // The shells with signal enough to read (ZONE_MIN_SHELL_ISIG), 20 equal in 1/d^2. - constexpr int n_shells = 20; - double min_s = std::numeric_limits::infinity(), max_s = 0.0; - for (const auto* r : usable) { - min_s = std::min(min_s, 1.0 / (r->d * r->d)); - max_s = std::max(max_s, 1.0 / (r->d * r->d)); - } - if (!(max_s > min_s)) - return result; - auto shell_of = [&](const MergedReflection* r) { - const double t = (1.0 / (r->d * r->d) - min_s) / (max_s - min_s); - return std::min(n_shells - 1, std::max(0, static_cast(t * n_shells))); - }; - std::vector isig_sum(n_shells, 0.0); - std::vector isig_n(n_shells, 0); - for (const auto* r : usable) { - isig_sum[shell_of(r)] += r->I / r->sigma; - isig_n[shell_of(r)] += 1; - } - std::vector strong; - for (const auto* r : usable) { - const int b = shell_of(r); - if (isig_n[b] > 0 && isig_sum[b] / isig_n[b] >= ZONE_MIN_SHELL_ISIG) - strong.push_back(r); - } + const auto strong = StrongReflections(p1_merged, gops, result); if (strong.empty()) return result; - result.d_max_A = 0.0; - result.d_min_A = std::numeric_limits::infinity(); - for (const auto* r : strong) { - result.d_max_A = std::max(result.d_max_A, r->d); - result.d_min_A = std::min(result.d_min_A, r->d); - } - std::vector control; for (const auto* r : strong) if (!gops.is_reflection_centric(gemmi::Op::Miller{{r->h, r->k, r->l}})) @@ -671,23 +733,8 @@ TwinImmuneZoneResult AnalyzeTwinImmuneZones(const std::vector& // Per hypothesis H, the zone: centric in the group, acentric in H - the reflections some added // operator sends to -h, i.e. the self-mates of that coset read as a twin law. - for (const auto& h_ops : subgroups) { - std::vector zone; - for (const auto* r : strong) { - const gemmi::Op::Miller h{{r->h, r->k, r->l}}; - const gemmi::Op::Miller minus{{-gemmi::Op::DEN * r->h, -gemmi::Op::DEN * r->k, -gemmi::Op::DEN * r->l}}; - const bool centric_in_h = std::any_of(h_ops.begin(), h_ops.end(), [&](const gemmi::Op& op) { - return op.apply_to_hkl_without_division(h) == minus; - }); - if (gops.is_reflection_centric(h) && !centric_in_h) - zone.push_back(r); - } - TwinImmuneZone z = ReadZone(zone, tncs_vector); - for (const auto& op : rotations) - if (!contains(h_ops, op)) - z.operators += (z.operators.empty() ? "" : " ") + op.as_hkl().triplet(); - result.zones.push_back(z); - } + for (const auto& h_ops : subgroups) + result.zones.push_back(ReadSubgroupZone(strong, gops, rotations, h_ops, tncs_vector)); return result; } diff --git a/image_analysis/scale_merge/TwinningAnalysis.h b/image_analysis/scale_merge/TwinningAnalysis.h index 259d89cdb..7165e065e 100644 --- a/image_analysis/scale_merge/TwinningAnalysis.h +++ b/image_analysis/scale_merge/TwinningAnalysis.h @@ -29,6 +29,14 @@ enum class TwinFractionSource { None, LTest, SecondMoment }; struct TwinningAnalysisResult { + // A twin law the run identified: the operator a promotion would have added, refused because its + // twin-immune zone read acentric (the operator relates unequal intensities on the very + // reflections a twin cannot touch), with the fraction the operator's own disagreement implies. + // Written as the mmCIF _pdbx_reflns_twin loop of the merge in the true (sub)group; empty when + // no law was identified. + std::string twin_law_operator; // as an hkl triplet, e.g. "k,h,-l" + double twin_law_fraction = 0.0; + int l_test_pairs = 0; double mean_abs_l = 0.0; // <|L|>: 0.5 untwinned, 0.375 perfect twin double mean_l_squared = 0.0; // : 0.333 untwinned, 0.2 perfect twin @@ -128,4 +136,10 @@ TwinImmuneZoneResult AnalyzeTwinImmuneZones(const std::vector& const gemmi::SpaceGroup& group, const std::array* tncs_vector = nullptr); +// The same for ONE hypothesis: the operators `group` adds over `subgroup` (one zone in the result, +// beside the control). Read where a promotion from the subgroup to the group is in question. +TwinImmuneZoneResult AnalyzeTwinImmuneZone(const std::vector& p1_merged, + const gemmi::SpaceGroup& group, const gemmi::SpaceGroup& subgroup, + const std::array* tncs_vector = nullptr); + std::string TwinImmuneZonesToText(const TwinImmuneZoneResult& result); diff --git a/rugnux/ResultReport.cpp b/rugnux/ResultReport.cpp index dd96d05fd..928e384a2 100644 --- a/rugnux/ResultReport.cpp +++ b/rugnux/ResultReport.cpp @@ -581,6 +581,13 @@ ReportDocument BuildReportDocument(const std::string &output_prefix, Add(s, Prose(fmt::format(" The two search merges disagreed and the higher point group was taken:\n {}.", result.space_group_arm_override))); } + if (!result.twin_zone_decision.empty()) { + Add(s, KeyText("TWIN_ZONE_DECISION", result.twin_zone_decision)); + Add(s, Prose(" A twin gate refused this promotion, and the twin-immune zone of the operators it\n" + " adds decided it (reflections a twin law cannot touch: centric if the operators\n" + " are real, acentric if they are a twin law or a pseudo-symmetry; margin 20 nats):\n" + " " + result.twin_zone_decision + ".")); + } if (refused) Add(s, Prose(fmt::format( " A promotion to {} was refused: {}.\n" @@ -1174,6 +1181,16 @@ ReportDocument BuildReportDocument(const std::string &output_prefix, " absorbed can only show there as an operator averaging unequal intensities. These\n" " numbers are not circular in that way.", true)); } + if (!result.twinning.twin_law_operator.empty()) { + Add(s, KeyText("TWIN_LAW", fmt::format("{} fraction {:.2f}", result.twinning.twin_law_operator, + result.twinning.twin_law_fraction))); + Add(s, Prose(fmt::format(" Twin law identified: operator {} at a fraction of about {:.2f} (a lower bound from\n" + " the operator's own disagreement). The mmCIF carries it as _pdbx_reflns_twin; refine\n" + " against these data in this space group with that law.", + result.twinning.twin_law_operator, result.twinning.twin_law_fraction))); + } + for (size_t i = 0; i < result.twin_law_evidence.size(); ++i) + Add(s, KeyText(fmt::format("TWIN_LAW_{}", i + 1).c_str(), result.twin_law_evidence[i])); if (result.twin_immune_zones && !result.twin_immune_zones->zones.empty()) { // Report-only evidence, one row per class of 2-folds of the adopted group. Not a decision: // the space group above was chosen without it. diff --git a/rugnux/Rugnux.cpp b/rugnux/Rugnux.cpp index e213ee9e2..ede65a3cd 100644 --- a/rugnux/Rugnux.cpp +++ b/rugnux/Rugnux.cpp @@ -1728,6 +1728,47 @@ namespace { // Asked twice, from the same numbers: in RunAllPasses, where the answer is acted on, and inside a // refined pass as soon as its own search merge is in - a pass that already knows it will be thrown // away leaves its report and its files unwritten (see the superseded flag in RunPipeline). + // The twin-immune zone of the operators `higher` adds over `lower`, read on a P1 merge, as a + // verdict: +1 the added operators are real (the zone is centric with margin), -1 they are a twin + // law or a pseudo-symmetry (acentric with margin), 0 undecided - fewer than two orders apart + // (the immunity argument holds for one coset), no zone reflections, or within the margin. + // + // The margin is the screw-axis convention (SearchSpaceGroupOptions::min_screw_absence_evidence): + // the same log-likelihood-ratio units, and the same bound of 20 nats. Read over three batteries + // the zones of genuine promotions sit at +60 nats and above and the zones behind the known + // twins at -290 nats and below, with one genuine trigonal crystal at -46 nats whose promotion + // no gate refused - so the bound is not what separates them, and a refusal a gate did fire is + // the only place the verdict is read. + int TwinZoneVerdict(const std::vector &p1_merged, const SearchSpaceGroupResult &higher, + const SearchSpaceGroupResult &lower, ProcessResult &result, + const std::array *tncs_vector = nullptr) { + constexpr double DECISIVE_NATS = 20.0; + if (!higher.point_group_representative || !lower.point_group_representative) + return 0; + if (higher.point_group_order != 2 * lower.point_group_order) + return 0; + const auto z = AnalyzeTwinImmuneZone(p1_merged, *higher.point_group_representative, + *lower.point_group_representative, tncs_vector); + if (z.zones.empty() || z.zones[0].n == 0) { + result.twin_zone_decision = fmt::format("{} over {}: no zone reflections in the shells with signal " + "({} merged reflections read) -> undecided", + higher.point_group_hm, lower.point_group_hm, p1_merged.size()); + return 0; + } + const auto &zone = z.zones[0]; + const int verdict = zone.evidence_nats <= -DECISIVE_NATS ? -1 + : zone.evidence_nats >= DECISIVE_NATS ? +1 : 0; + result.twin_zone_decision = fmt::format( + "{} over {}: operators {}; n {} <|E^2-1|> {:.3f} +- {:.3f} (control {:.3f}), evidence " + "{:+.1f} nats ({:.2f}-{:.2f} A{}) -> {}", + higher.point_group_hm, lower.point_group_hm, zone.operators, zone.n, zone.mean_abs_e2_minus_1, + zone.standard_error, z.control.mean_abs_e2_minus_1, zone.evidence_nats, z.d_max_A, z.d_min_A, + z.tncs_normalised ? ", normalised per pseudo-translation class" : "", + verdict < 0 ? "acentric, the added operators are a twin law or a pseudo-symmetry" + : verdict > 0 ? "centric, the added operators are real" : "undecided"); + return verdict; + } + std::string RefinedPassIsWorse(const ProcessResult &pass1, const ProcessResult &pass2) { constexpr double MAX_CREDIBLE_COMPLETENESS = 100.5; // rounding headroom, nothing more // How much of the signal the refined pass has to lose before the run moves back off the @@ -5456,7 +5497,7 @@ ProcessResult Rugnux::RunPipeline(RugnuxObserver *observer, bool write_output, b rsm->SetSearchMinZeta(zeta); merged_filtered_isa = sg_opts.merge_isa; // the filtered arm's, before it is replaced sg_opts.merge_isa = result.error_model_isa; // this arm's own error model - const auto alt = SearchSpaceGroup(sm_all.merged, sg_opts); + auto alt = SearchSpaceGroup(sm_all.merged, sg_opts); // The order of the point group each arm confirmed. Read from the search, not from the // space group it went on to pick: Stage B leaves best_space_group unset when no // candidate has enough absences to be eligible, which is common on the filtered arm @@ -5524,13 +5565,49 @@ ProcessResult Rugnux::RunPipeline(RugnuxObserver *observer, bool write_output, b logger.Warning("Space-group search: {}", msg); result.space_group_arm_override = msg; }; + // A refusal is not simply outvoted by the other arm's confirmation: the gates read + // the operators' own disagreement, which a partial twin at a fraction the other arm's + // coverage happens to hide passes there (an H3 partial twin promoted to R32 by the + // filtered arm; a P31 one to P3121 by the all-observation arm). What decides is the + // twin-immune zone of the added operators, read on the all-observation P1 merge + // (TwinZoneVerdict): acentric with margin and the refusal stands, on all observations; + // centric with margin and the higher group is taken as before; undecided and the rule + // stays as it was. + int zone_verdict = 0; if (order_of(alt) > order_of(sg_search)) { logger.Info("Space-group search: all-observation merge supports {} where the " "Lorentz-filtered one supports {} - taking the higher symmetry", alt.point_group_hm, sg_search.point_group_hm); overridden(sg_search, "Lorentz-filtered", "all-observation"); + zone_verdict = !sg_search.refused_point_group_hm.empty() + ? TwinZoneVerdict(sm_all.merged, alt, sg_search, result) : 0; + if (zone_verdict < 0) { + logger.Warning("Space-group search: the Lorentz-filtered merge's refusal of {} " + "STANDS - the twin-immune zone of its added operators reads " + "acentric; keeping {}, judged on all observations", + sg_search.refused_point_group_hm, sg_search.point_group_hm); + sg_opts.fixed_point_group = sg_search.point_group_representative; + auto lower = SearchSpaceGroup(sm_all.merged, sg_opts); + sg_opts.fixed_point_group.reset(); + lower.refused_point_group_hm = sg_search.refused_point_group_hm; + lower.refused_reason = sg_search.refused_reason + ", and its twin-immune zone reads acentric"; + lower.refused_point_group_representative = sg_search.refused_point_group_representative; + lower.refused_by_twin_gate = true; + lower.refused_twin_fraction = sg_search.refused_twin_fraction; + alt = std::move(lower); + } } - if (order_of(alt) < order_of(sg_search)) { + if (order_of(alt) < order_of(sg_search) + && !alt.refused_point_group_hm.empty() + && TwinZoneVerdict(sm_all.merged, sg_search, alt, result) < 0) { + logger.Warning("Space-group search: the all-observation merge's refusal of {} STANDS " + "- the twin-immune zone of its added operators reads acentric; keeping {}", + alt.refused_point_group_hm, alt.point_group_hm); + overridden(alt, "all-observation", "Lorentz-filtered"); + result.space_group_arm_override += " - but the refusal stands (see TWIN_ZONE_DECISION)"; + alt.refused_reason += ", and its twin-immune zone reads acentric"; + sg_search = alt; + } else if (order_of(alt) < order_of(sg_search)) { // The filtered arm found symmetry the all-observation arm did not. Discarding it // was costing real point groups: over the corpus the two arms disagree on eight // crystals and the higher one is right on all eight, because the filter removes @@ -6293,6 +6370,56 @@ ProcessResult Rugnux::RunPipeline(RugnuxObserver *observer, bool write_output, b else for (const auto &alt : hi_search.alternatives) if (alt.centring_type() == sg.centring_type()) { hi_sg = alt; break; } + // A refusal is arbitrated by the twin-immune zone of the added operators + // (TwinZoneVerdict) where it is decisive, and only otherwise by the merge + // comparison below: that comparison reads R_meas and ISa of two merges whose + // per-frame scales have settled, and the lower group, with the same scales fitted + // against fewer equivalents, then agrees with itself the better of the two on a + // genuine promotion as much as on a twin (measured: a genuine 2 -> 222 step reading + // R_meas 0.094 -> 0.103, ISa 12.3 -> 10.9). The zone does not depend on the scales. + // Read on the adopted group's own merge: the zone reflections are centric in the + // refused group and acentric in the adopted one, so they are distinct reflections + // of this merge, at full multiplicity and production scale - where the P1 search + // merge of a weak crystal has no shell with signal enough to read a zone on. + const int zone = hi_sg.has_value() + ? TwinZoneVerdict(sm.merged, hi_search, sg_search, result, + TranslationalNCSVectorForLTest(pre_tncs)) : 0; + if (zone < 0) { + const std::string msg = fmt::format( + "Point group {} was refused ({}), and the twin-immune zone of its added " + "operators reads acentric: they relate unequal intensities on the very " + "reflections a twin law cannot touch, so the refusal stands and the " + "operator is recorded as a twin law. Keeping {}.", + sg_search.refused_point_group_hm, sg_search.refused_reason, sg.xhm()); + logger.Info("{}", msg); + stats_text << " " << msg << "\n\n"; + sg_search.refused_reason += ", and its twin-immune zone reads acentric"; + hi_sg.reset(); + } else if (zone > 0) { + const std::string msg = fmt::format( + "Point group {} was confirmed by the operator correlations and then " + "refused ({}), but the twin-immune zone of its added operators reads " + "centric - a twin law cannot produce that on the reflections it leaves " + "untouched - so {} is adopted.", + sg_search.refused_point_group_hm, sg_search.refused_reason, hi_sg->xhm()); + logger.Info("{}", msg); + stats_text << " " << msg << "\n\n"; + sg_search = hi_search; + if (hi_search.best_space_group->number != hi_sg->number) { + sg_search.alternatives.push_back(*hi_search.best_space_group); + std::erase_if(sg_search.alternatives, + [&](const gemmi::SpaceGroup &a) { return a.number == hi_sg->number; }); + } + sg_search.best_space_group = *hi_sg; + result.space_group = *hi_sg; + end_msg.space_group_name = hi_sg->xhm(); + end_msg.space_group_number = static_cast(hi_sg->number); + promoted_point_group = true; + experiment_.SetSpaceGroup(*hi_sg); + phase("Re-scaling in space group " + hi_sg->short_name()); + sm = scale_and_merge(hi_sg->short_name(), false); + hi_sg.reset(); + } if (hi_sg.has_value()) { // scale_and_merge reports the error model of whatever it merged, and the two // comparison merges are not the run's answer, so it goes back if they lose. @@ -6471,6 +6598,30 @@ ProcessResult Rugnux::RunPipeline(RugnuxObserver *observer, bool write_output, b // flat one landing on exactly the case the flag exists for. (Assigning it before the call // would not do: the call replaces the whole struct.) result.twinning.laue_class_was_chosen_by_promotion = promoted_point_group; + // A refusal that stood on the twin-immune zone names the law: the first operator the + // refused group adds, at the fraction its own disagreement implies (a lower bound). + if (result.space_group_search && result.space_group_search->refused_point_group_representative + && result.twin_zone_decision.find("acentric, the added") != std::string::npos) { + const auto &sgs = *result.space_group_search; + const gemmi::GroupOps hi = sgs.refused_point_group_representative->operations(); + const gemmi::GroupOps lo = twin_sg->operations(); + for (const auto &op : hi.derive_symmorphic().sym_ops) { + if (op.det_rot() <= 0) continue; + const bool in_lower = std::any_of(lo.sym_ops.begin(), lo.sym_ops.end(), + [&](const gemmi::Op &o) { return o.rot == op.rot; }); + if (in_lower) continue; + result.twinning.twin_law_operator = gemmi::Op{op.rot, {0, 0, 0}, 'x'}.as_hkl().triplet(); + break; + } + // The fraction: the refused operators' own H where the H gate measured it, else the + // L-test of the merge before the search (a twin fraction that does not depend on the + // promotion), else the perfect twin every operator statistic reads as symmetry. + result.twinning.twin_law_fraction = + std::isfinite(sgs.refused_twin_fraction) ? sgs.refused_twin_fraction + : result.pre_promotion_twinning + && result.pre_promotion_twinning->twin_fraction_source != TwinFractionSource::None + ? result.pre_promotion_twinning->estimated_twin_fraction : 0.5; + } if (result.tncs.measurable) stats_text << TranslationalNCSToText(result.tncs) << "\n"; stats_text << TwinningAnalysisToText(result.twinning) << "\n"; @@ -6548,6 +6699,26 @@ ProcessResult Rugnux::RunPipeline(RugnuxObserver *observer, bool write_output, b if (result.consensus_cell && twin_sg != nullptr) { const auto twin_ops = ReindexAmbiguityOperators(*result.consensus_cell, *twin_sg, 2.0); if (!twin_ops.empty()) { + // The merge is folded under the adopted group, and a twin law sends a reflection + // outside that group's asymmetric unit - so the pairs are formed on the merge + // expanded to P1 under the group's own operations (each reflection once per + // operation; the H statistic is a median and the correlation a ratio, so the + // repetition changes neither). + std::vector expanded; + const auto expanded_merge = [&]() -> const std::vector & { + if (expanded.empty()) { + const gemmi::GroupOps ops = twin_sg->operations(); + expanded.reserve(sm.merged.size() * ops.sym_ops.size()); + for (const auto &r : sm.merged) + for (const auto &o : ops.sym_ops) { + const auto hkl = o.apply_to_hkl({{r.h, r.k, r.l}}); + MergedReflection e = r; + e.h = hkl[0]; e.k = hkl[1]; e.l = hkl[2]; + expanded.push_back(e); + } + } + return expanded; + }; std::string laws; for (const auto &op : twin_ops) { std::string t = op.triplet(); @@ -6555,7 +6726,25 @@ ProcessResult Rugnux::RunPipeline(RugnuxObserver *observer, bool write_output, b std::replace(t.begin(), t.end(), 'y', 'k'); std::replace(t.begin(), t.end(), 'z', 'l'); laws += (laws.empty() ? "" : " ; ") + t; + // What each law reads on the merge: the disagreement H of the reflections it + // relates (Yeates (1997) Methods Enzymol. 276, 344-358: a twin of fraction a reads + // (1-2a)/2, so a >= 0.5 - H), their correlation and their intensity-weighted R. + // Report-only, so a user sees which law a twin refinement would need. + gemmi::Mat33 m; + for (int i = 0; i < 3; ++i) + for (int j = 0; j < 3; ++j) + m[j][i] = static_cast(op.rot[i][j]) / gemmi::Op::DEN; + SearchSpaceGroupOptions law_opts; + law_opts.nthreads = static_cast(std::max(1, config_.nthreads)); + if (const auto s = OperatorCorrelation(expanded_merge(), m, law_opts); s.has_value()) + result.twin_law_evidence.push_back(fmt::format( + "{}: {} pairs, H {:.3f} (twin fraction {:.2f} or more), R {:.3f}, CC {:.3f}", + t, s->n_pairs, s->h_stat, std::max(0.0, 0.5 - s->h_stat), s->r_stat, s->cc)); + else + result.twin_law_evidence.push_back(fmt::format("{}: too few pairs to read", t)); } + for (const auto &e : result.twin_law_evidence) + logger.Info("Twin law {}", e); // A model can resolve it too, but whether it does is only known once the model has // been fitted (validation step below), so the warning stands here exactly as in a run // without a model, and is withdrawn there if the model's indexing probe decided it. diff --git a/rugnux/Rugnux.h b/rugnux/Rugnux.h index 45b68f3a6..4e0d1f819 100644 --- a/rugnux/Rugnux.h +++ b/rugnux/Rugnux.h @@ -351,6 +351,12 @@ struct ProcessResult { // group was taken from one of them: what the other arm said - which gate refused the promotion, // or that it never confirmed the operators. Empty when the arms agreed. std::string space_group_arm_override; + // The twin-immune zone read for a promotion a twin gate refused (the H ratio or the added-operator + // R), and what was decided on it. Empty when no twin gate fired. + std::string twin_zone_decision; + // Per lattice twin law outside the adopted group: the operator's own H, the fraction it implies + // and its correlation, on the final merge. Report-only. + std::vector twin_law_evidence; // ---- Material for the results report (_report.txt, see rugnux/ResultReport.h) ----