From 724430022f9d8d8be29a9f2c0851a64edd89ce0b Mon Sep 17 00:00:00 2001 From: Filip Leonarski Date: Fri, 13 Nov 2026 23:26:42 +0100 Subject: [PATCH 001/229] tNCS analysis: phase classes from per-axis exp tables, not a libm cosine each The pseudo-translation searches (the gate's vector search and its 20 permutation nulls, the lattice-averaged search with up to 12 rotation images, and the full-resolution ladder) evaluate cos(2 pi h.u) thousands of times over up to a few hundred thousand reflections. On a rotation run with a hexagonal lattice and a pseudo-translation, the libm cosine under CosineCorrelation was ~40% of all CPU samples of the whole run, and the pre-promotion analysis on the P1 all-observation merge sat on the critical path of the space-group step for 4-7 s. cos(2 pi (h u_x + k u_y + l u_z)) is now the real part of the product of three table entries exp(2 pi i m u_axis), built once per evaluation (ClassTable); contrast_over shares it. Measured on a rotation set (1800 images, P3_221, three copies with tNCS), offline and --simulate-live --fast-live: pre-promotion wait 5.5-5.7 s -> 0.2-0.3 s, final tNCS analysis 1.3-1.9 s -> 0.3-0.4 s. Report, merged MTZ reflections, placed and refined models identical to the previous binary. [tncs] and twinning tests pass. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01HVeDQsU5a8AJUdJPgWevAK --- .../scale_merge/TranslationalNCS.cpp | 56 +++++++++++++++++-- 1 file changed, 51 insertions(+), 5 deletions(-) diff --git a/image_analysis/scale_merge/TranslationalNCS.cpp b/image_analysis/scale_merge/TranslationalNCS.cpp index c72909778..f76e569d9 100644 --- a/image_analysis/scale_merge/TranslationalNCS.cpp +++ b/image_analysis/scale_merge/TranslationalNCS.cpp @@ -161,6 +161,52 @@ namespace { return best; } + // TncsClass - cos(2 pi h.v) averaged over `vectors` - for every h up to the order m_max, as the real + // part of exp(2 pi i h v_x) exp(2 pi i k v_y) exp(2 pi i l v_z), each factor read from a table over + // the orders: the searches below ask for it thousands of times on up to a few hundred thousand + // reflections, and a libm cosine per reflection per vector made it most of the CPU time of a whole + // run on a merge in P1. + class ClassTable { + public: + ClassTable(const std::vector> &vectors, int m_max) + : m_max_(m_max), width_(2 * m_max + 1), count_(vectors.size()), + re_(count_ * 3 * width_), im_(count_ * 3 * width_) { + for (size_t v = 0; v < count_; ++v) + for (int axis = 0; axis < 3; ++axis) + for (int m = -m_max; m <= m_max; ++m) { + const double phase = 2.0 * std::numbers::pi * m * vectors[v][axis]; + re_[(v * 3 + axis) * width_ + (m_max + m)] = std::cos(phase); + im_[(v * 3 + axis) * width_ + (m_max + m)] = std::sin(phase); + } + } + + double operator()(const std::array &h) const { + double c = 0.0; + for (size_t v = 0; v < count_; ++v) { + const size_t a = v * 3 * width_ + (m_max_ + h[0]); + const size_t b = (v * 3 + 1) * width_ + (m_max_ + h[1]); + const size_t d = (v * 3 + 2) * width_ + (m_max_ + h[2]); + const double ab_re = re_[a] * re_[b] - im_[a] * im_[b]; + const double ab_im = re_[a] * im_[b] + im_[a] * re_[b]; + c += ab_re * re_[d] - ab_im * im_[d]; + } + return c / static_cast(count_); + } + + private: + int m_max_; + size_t width_, count_; + std::vector re_, im_; + }; + + // The highest |index| among the first `n` reflections: the order a ClassTable for them reaches. + int MaxOrder(const std::vector> &hkl, size_t n) { + int m_max = 0; + for (size_t i = 0; i < n; ++i) + m_max = std::max({m_max, std::abs(hkl[i][0]), std::abs(hkl[i][1]), std::abs(hkl[i][2])}); + return m_max; + } + // How well a vector explains the intensities of the first `n` reflections under the physical // model = A (1 + f cos(2 pi h.u)): the correlation between E^2 and cos(2 pi h.u). // @@ -177,10 +223,10 @@ namespace { // With `rots` the cosine is the class averaged over them (see `modulation_averaged`). double CosineCorrelation(const std::vector> &hkl, const std::vector &e2, const std::array &u, size_t n, const std::vector &rots) { - const auto vectors = Images(u, rots); + const ClassTable cls(Images(u, rots), MaxOrder(hkl, n)); double sc = 0.0, scc = 0.0, sy = 0.0, syy = 0.0, scy = 0.0; for (size_t i = 0; i < n; ++i) { - const double c = TncsClass(hkl[i][0], hkl[i][1], hkl[i][2], vectors); + const double c = cls(hkl[i]); sc += c; scc += c * c; sy += e2[i]; @@ -574,9 +620,10 @@ TranslationalNCSResult AnalyzeTranslationalNCS(const std::vector)/pi, which for the identity alone is the same phase folded // about 1/2 - the bins then centred on the strongest and the weakest class. + const int mod_max_order = MaxOrder(mod_hkl, mod_hkl.size()); auto contrast_over = [&](const std::vector &e2v, const std::array &u, std::vector *profile, const std::vector &rots) { - const auto vectors = Images(u, rots); + const ClassTable cls(Images(u, rots), mod_max_order); std::array sum{}, cnt{}; sum.fill(0.0); cnt.fill(0.0); @@ -586,8 +633,7 @@ TranslationalNCSResult AnalyzeTranslationalNCS(const std::vector(f * kPhaseBins), kPhaseBins - 1); sum[b] += e2v[i]; cnt[b] += 1.0; -- 2.54.1 From 344912139adcc3cba77d91a3c9c6806a4209ed08 Mon Sep 17 00:00:00 2001 From: Filip Leonarski Date: Fri, 13 Nov 2026 23:33:46 +0100 Subject: [PATCH 002/229] Refinement twin null: each unrelated mate on its own anisotropic scale The twin null replaces a law's mates by unrelated reflections of the same resolution and asks what averaging alone buys. TwinnedModel puts a mate on the scale k_total of the reflection it is the mate of - right for a twin law, whose domain reflection is measured at the same spot - but an unrelated mate lies in another direction, where the anisotropic scale can differ many times over. On a trigonal crystal with a pseudo-translation, refined from a model whose atomic U carried the anisotropy opposite to k_total, a weak reflection's random mate was put on a scale 22 times its own (amplitude, at 2 A): the null R-free read 0.466 against an untwinned 0.406, and a law at fraction 0.04 was adopted 7.9 standard errors ahead of it. With each mate on its own scale the null reads 0.400 (z 0.8, untwinned); the same crystal's experimental model, adopted twinned at z 3.1 in rc186, reads z 0.6. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01HVeDQsU5a8AJUdJPgWevAK --- .../structure_refinement/Refinement.cpp | 24 ++++++++++++++++++- 1 file changed, 23 insertions(+), 1 deletion(-) diff --git a/image_analysis/structure_refinement/Refinement.cpp b/image_analysis/structure_refinement/Refinement.cpp index 07f0e089c..cb1e3406e 100644 --- a/image_analysis/structure_refinement/Refinement.cpp +++ b/image_analysis/structure_refinement/Refinement.cpp @@ -1450,7 +1450,29 @@ void TwinNull(const Context &ctx, RefinementResult &result, size_t first = 0) { for (size_t d = first; d < a.size(); d++) result.twin_fraction_null += a[d]; } - const std::vector> f_null = TwinnedModel(null, rows, ctx.fcalc); + // TwinnedModel with each unrelated mate on its own scale k_total: TwinnedModel puts a mate on the scale of the + // reflection it is the mate of, as the twin domain's reflection at the same spot is measured, but an unrelated + // mate lies in another direction, where the anisotropic scale can differ many times over (22 times in amplitude + // at 2 A, on a model whose U carried the anisotropy opposite to k_total), and on the reflection's scale it put + // the null 0.06 in R-free above the untwinned refinement - a law "ahead" of its null by 7.9 standard errors at a + // fraction of 0.04. + std::vector> f_null(n); + double own_fraction = 1.0; + for (float a : rows.twin_fractions) + own_fraction -= a; + for (size_t m = 0; m < n; m++) { + const std::complex u = std::complex(ctx.fcalc[m]) + std::complex(rows.fmask[m]); + double i_model = own_fraction * rows.k_total[m] * rows.k_total[m] * std::norm(u); + for (size_t d = 0; d < null.Laws(); d++) { + const int j = null.mates[d][m]; + const double k = d < first ? rows.k_total[m] : rows.k_total[j]; + i_model += rows.twin_fractions[d] * k * k * + std::norm(std::complex(ctx.fcalc[j]) + std::complex(rows.fmask[j])); + } + const double amplitude = std::sqrt(std::max(i_model, 0.0)); + f_null[m] = std::norm(u) > 0 ? std::complex(u * (amplitude / std::abs(u))) + : std::complex(static_cast(amplitude), 0); + } result.twin_r_free_null = ComputeRFactors(null, f_null).r_free; // How far the laws beat their null on the free reflections, paired: the mean of |Fo - |F_null|| - |Fo - |F_twin|| // over its standard error. The members of a free twin group share their F_calc, so their terms are summed into -- 2.54.1 From a22d8b9b56dfdb7d0c2e0b2c3c018d14277cb79f Mon Sep 17 00:00:00 2001 From: Filip Leonarski Date: Sat, 14 Nov 2026 00:03:24 +0100 Subject: [PATCH 003/229] Live MR: carry the pre-pass placement across the lattice's indexing ambiguity In a live run the molecular replacement of a prediction starts on the geometry pre-pass's merge and its placement is carried to the final merge where it holds there. The two passes index the sweep each on its own, so on a lattice with an indexing ambiguity the final merge can come out in the other hand, the carried placement then fits at R-free ~0.6 and the whole search is run again after the space-group step, on the critical path of the tail. CarryMolecularReplacement now picks the ambiguity operator (identity included) that takes the searched merge's reflections onto this merge's by the correlation of their intensities - a pass over the reflections, milliseconds - and turns the copies by it before the rigid body. Measured on a P3_221 rotation set with three copies and tNCS (--simulate-live 10 --fast-live, 1800 images): the pre-pass placement, turned by -h,-k,l, holds at R-free 0.417 (the re-search reached 0.413); MR step 0.91-1.40 s -> 0.18-0.26 s. Refined R-free 0.4175 against 0.4255 from the re-searched placement (same merge, same refinement). New test MolecularReplacement_CarryAcrossIndexingAmbiguity (fails on the old code at R-free 0.51). Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01HVeDQsU5a8AJUdJPgWevAK --- .../MolecularReplacement.cpp | 62 +++++++++++++++++-- tests/MolecularReplacementTest.cpp | 51 +++++++++++++++ 2 files changed, 107 insertions(+), 6 deletions(-) diff --git a/image_analysis/structure_refinement/MolecularReplacement.cpp b/image_analysis/structure_refinement/MolecularReplacement.cpp index 087b0e94c..8d9bf7a72 100644 --- a/image_analysis/structure_refinement/MolecularReplacement.cpp +++ b/image_analysis/structure_refinement/MolecularReplacement.cpp @@ -26,6 +26,8 @@ #include // DensityCalculator #include // IT92 x-ray form factors #include // Scaling (bulk solvent + anisotropic B) +#include // find_twin_laws +#include // ReciprocalAsu #include "../../common/JFJochMath.h" // PI #include "../../common/Logger.h" @@ -4092,6 +4094,46 @@ MolecularReplacementResult RunMolecularReplacement(const RugnuxModel &model, con return result; } +// The operator of the lattice's indexing ambiguity (the identity among them) that takes the reflections of `searched` +// onto those of `merge`, by the correlation of their intensities: the two passes of a run index the sweep each on +// its own, and a lattice with an ambiguity can come out in either hand of it. +static gemmi::Op AmbiguityBetween(const MRMerge &searched, const MRMerge &merge, const gemmi::SpaceGroup &sg) { + const gemmi::GroupOps gops = sg.operations(); + const gemmi::ReciprocalAsu asu(&sg); + std::unordered_map intensity; + const auto key = [&](const gemmi::Miller &h) { + const gemmi::Miller a = asu.to_asu(h, gops).first; + return (static_cast(a[0] + 512) << 20) | (static_cast(a[1] + 512) << 10) | (a[2] + 512); + }; + for (const MergedReflection &r : *merge.merged) + if (std::isfinite(r.I)) + intensity[key({{r.h, r.k, r.l}})] = r.I; + gemmi::Op best = gemmi::Op::identity(); + double best_cc = -2.0; + std::vector ops{gemmi::Op::identity()}; + for (const gemmi::Op &op : gemmi::find_twin_laws(gemmi::UnitCell(merge.cell), &sg, 3.0, false)) + ops.push_back(op); + for (const gemmi::Op &op : ops) { + double n = 0, sx = 0, sy = 0, sxx = 0, syy = 0, sxy = 0; + for (const MergedReflection &r : *searched.merged) { + if (!std::isfinite(r.I)) + continue; + const auto it = intensity.find(key(op.apply_to_hkl({{r.h, r.k, r.l}}))); + if (it == intensity.end()) + continue; + n += 1; + sx += r.I; sy += it->second; + sxx += r.I * r.I; syy += it->second * it->second; sxy += r.I * it->second; + } + const double cc = n > 1 ? (sxy - sx * sy / n) / std::sqrt((sxx - sx * sx / n) * (syy - sy * sy / n)) : -1.0; + if (cc > best_cc) { + best_cc = cc; + best = op; + } + } + return best; +} + std::optional CarryMolecularReplacement(const MolecularReplacementResult &early, const MRMerge &searched, const MRMerge &merge, Logger &logger, size_t nthreads, @@ -4117,12 +4159,18 @@ std::optional CarryMolecularReplacement(const Molecu if (r.d > 0) data_d_min = std::min(data_d_min, r.d); const double d_min = std::max(SCORE_D_MIN, data_d_min); - // Every copy at its fractional position in this cell. + // Every copy at its fractional position in this cell, turned by the indexing ambiguity between the two merges: + // a reflection h of `searched` is op(h) here, so a position x there is op^-1 x here. + const gemmi::Op op = AmbiguityBetween(searched, merge, sg); + const gemmi::Op to_here = op.inverse(); std::vector body = SplitCopies(*c.placed, c.copies); for (gemmi::Structure &b : body) { std::vector pos = ModelPositions(b.models[0]); - for (gemmi::Position &x : pos) - x = cell.orthogonalize(b.cell.fractionalize(x)); + for (gemmi::Position &x : pos) { + const gemmi::Fractional f = b.cell.fractionalize(x); + const std::array t = to_here.apply_to_xyz({f.x, f.y, f.z}); + x = cell.orthogonalize(gemmi::Fractional(t[0], t[1], t[2])); + } SetModelPositions(b.models[0], pos); b.cell = cell; b.spacegroup_hm = sg.xhm(); @@ -4165,9 +4213,11 @@ std::optional CarryMolecularReplacement(const Molecu auto placed = std::make_shared(AssembleCopies(body)); const PlacementScore score = score_placement(*placed, sg, *merge.merged, d_min, nthreads, &scorers); const bool holds = score.r_free <= c.r_free + R_FREE_MARGIN; - logger.Info("Molecular replacement: the search on the {} ({}): its placement in {} ({} copies, R-free {:.3f} there) refined against " - "this merge: R-work {:.3f} R-free {:.3f} ({:.2f} s) - {}", searched.name, - early.decision, sg.xhm(), c.copies, c.r_free, score.r_work, score.r_free, + logger.Info("Molecular replacement: the search on the {} ({}): its placement in {} ({} copies, R-free {:.3f} there){} " + "refined against this merge: R-work {:.3f} R-free {:.3f} ({:.2f} s) - {}", searched.name, + early.decision, sg.xhm(), c.copies, c.r_free, + op == gemmi::Op::identity() ? std::string() : ", indexed there as " + op.as_hkl().triplet('h') + " here,", + score.r_work, score.r_free, seconds_since(t0), holds ? "it holds, not searched again" : "it does not hold, searched again"); if (!holds) return std::nullopt; diff --git a/tests/MolecularReplacementTest.cpp b/tests/MolecularReplacementTest.cpp index e51635d5f..a2deea5e0 100644 --- a/tests/MolecularReplacementTest.cpp +++ b/tests/MolecularReplacementTest.cpp @@ -13,6 +13,7 @@ #include #include +#include #include "../image_analysis/structure_refinement/ModelFFT.h" #include "../image_analysis/structure_refinement/MolecularReplacement.h" @@ -817,6 +818,56 @@ TEST_CASE("MolecularReplacement_CarryToAnotherMerge", "[MolecularReplacement]") CHECK_FALSE(CarryMolecularReplacement(early, searched, {"MERGE", &merged, uc, other}, logger, 4)); } +// The two merges of one crystal in the two hands of its indexing ambiguity (P 41: k,h,-l), as two passes that index +// the sweep each on its own can give: the placement found on the one is turned onto the other (here up to a symmetry operator of the group) and +// holds there. +TEST_CASE("MolecularReplacement_CarryAcrossIndexingAmbiguity", "[MolecularReplacement]") { + const SearchModel model = synthetic_model(); + const gemmi::SpaceGroup &sg = gemmi::get_spacegroup_by_name("P 41"); + const gemmi::UnitCell cell(60, 60, 70, 90, 90, 90); + const gemmi::Structure truth = PlaceSearchModel(model, axis_angle({1, 2, 3}, 50), gemmi::Fractional(0.17, 0.31, 0.09), + cell, sg); + auto merged = observed(truth); + for (size_t i = 0; i < merged.size(); i++) + merged[i].rfree_flag = i % 10 == 0; + // The other hand: every reflection h of this merge is op(h) there, and the model placed there is op^-1 x. + const gemmi::Op op = gemmi::parse_triplet("y,x,-z"); + const gemmi::GroupOps gops = sg.operations(); + const gemmi::ReciprocalAsu asu(&sg); + std::vector other_hand = merged; + for (MergedReflection &r : other_hand) { + const gemmi::Miller h = asu.to_asu(op.apply_to_hkl({{r.h, r.k, r.l}}), gops).first; + r.h = h[0]; r.k = h[1]; r.l = h[2]; + } + gemmi::Structure there = truth; + std::vector pos = ModelPositions(there.models[0]); + for (gemmi::Position &x : pos) { + const gemmi::Fractional f = cell.fractionalize(x); + const std::array t = op.inverse().apply_to_xyz({f.x, f.y, f.z}); + x = cell.orthogonalize(gemmi::Fractional(t[0], t[1], t[2])); + } + SetModelPositions(there.models[0], pos); + + MolecularReplacementResult early; + early.ok = true; + early.chosen = 0; + early.decision = "AGREES"; + MRCandidate c; + c.space_group = sg; + c.copies = 1; + c.r_free = 0.30; + c.placed = std::make_shared(there); + early.candidates.push_back(c); + + const UnitCell uc{60, 60, 70, 90, 90, 90}; + Logger logger("MolecularReplacement_CarryAcrossIndexingAmbiguity"); + const auto carried = CarryMolecularReplacement(early, {"first merge", &other_hand, uc, sg}, + {"MERGE", &merged, uc, sg}, logger, 4); + // the placement as it came, untouched by the ambiguity, fits this merge at R-free 0.5 and more + REQUIRE(carried); + CHECK(carried->candidates[0].r_free < 0.2); +} + #ifdef JFJOCH_USE_CUDA TEST_CASE("MolecularReplacement_GPUMatchesCPU", "[MolecularReplacement]") { if (get_gpu_count() == 0) -- 2.54.1 From 77737e25825b08a3ed4d2cb5c55b00a3c29180d1 Mon Sep 17 00:00:00 2001 From: Filip Leonarski Date: Sat, 14 Nov 2026 00:42:14 +0100 Subject: [PATCH 004/229] Decay and per-batch relative B tilt each frame about its own mean s^2 The per-frame scale G already holds each frame's average scale, so a radiation-damage B only tilts a frame about the frame's (I/sigma)^2-weighted mean s^2. The single-sweep decay and the per-batch relative B were fitted and applied about s^2 = 0 instead: the fit was attenuated (it had to explain frame offsets G had already removed) and the applied factor moved every frame's average a second time, which the even/odd-frame cross-validation then scored as a loss. Measured: a synthetic single sweep whose B rises 0 -> 10 A^2 now fits 8.95 A^2 (before 2.74), and its high-resolution fulls come out on one scale from first to last frame (new test). The two-sweep synthetic with a 3 A^2 step now fits 3.43 (before 0.97) and applies it (GPU hash re-pinned; the CPU pin is not reproducible on this machine at the base either). On the rotation battery the decay was never applied: the six damaged in-house sets read held-out gains of -17%, -146%, -8%, -3%, -3% - the signature of the double-applied average. With the fix they read -1.1, -0.2, -6.2, -3.1 and a negligible dB; still skipped, and no merged result moves beyond noise (guard: 10-set battery + those 5 sets against the rc186 baseline, only time differs). On a 360 deg trigonal sweep with relative B +11 A^2 the decay fit goes 2.91 -> 6.45 A^2, held-out gain -3.8% -> +0.4% (still under the 2% gate). The second-crystal stretch test passed only because the spurious decay (-19.9 A^2 on data with no B) gave the partials arm a resolved error model; on error-free synthetic data the run takes the fulls-alone merge, which the test is not about, so the test data get a 3% proportional error. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01HVeDQsU5a8AJUdJPgWevAK --- .../scale_merge/RotationScaleMerge.cpp | 53 +++++++++++++------ .../scale_merge/RotationScaleMerge.h | 8 ++- tests/RotationScaleMergeSegmentsTest.cpp | 30 ++++++++++- 3 files changed, 73 insertions(+), 18 deletions(-) diff --git a/image_analysis/scale_merge/RotationScaleMerge.cpp b/image_analysis/scale_merge/RotationScaleMerge.cpp index 6f87043b7..7818ea042 100644 --- a/image_analysis/scale_merge/RotationScaleMerge.cpp +++ b/image_analysis/scale_merge/RotationScaleMerge.cpp @@ -2367,10 +2367,26 @@ void RotationScaleMerge::BuildDecayTerms(int n_groups, DecayTerms &t) const { for (const DecayTerm &d : t.term) t.gterm[fill[d.group]++] = d; } +std::vector RotationScaleMerge::FrameMeanS2(const DecayTerms &t) const { + std::vector sw(n_frames, 0.0), sws2(n_frames, 0.0); + for (const DecayTerm &o : t.term) { + if (!(o.I > 0.0f)) continue; + const double w = (static_cast(o.I) / o.sigma) * (static_cast(o.I) / o.sigma); + sw[o.frame] += w; + sws2[o.frame] += w / (4.0 * static_cast(o.d) * o.d); + } + std::vector m(n_frames, 0.0); + for (int f = 0; f < n_frames; ++f) + if (sw[f] > 0.0) m[f] = sws2[f] / sw[f]; + return m; +} + void RotationScaleMerge::RefineDecay(int n_groups) { // Radiation damage weakens later frames more at higher resolution - a resolution x time (Debye-Waller) // systematic the resolution-flat per-frame G leaves in. Model it as a single global relative-B rate: - // ln(I_ref / I_obs) = slope * (frame - frame_center) * s^2, s^2 = 1/(4 d^2), slope = 2 dB/dframe, + // ln(I_ref / I_obs) = slope * (frame - frame_center) * (s^2 - _frame), s^2 = 1/(4 d^2), + // slope = 2 dB/dframe, with s^2 about the frame's own mean because the per-frame G already holds the + // frame's average scale - applied about s^2 = 0 the correction would move that average a second time, // fitted (inverse-variance-of-log weighted) against the merged reference. // // The fit is dominated by strong LOW-res reflections and EXTRAPOLATED to high s^2, so a slope fitted to @@ -2395,8 +2411,11 @@ void RotationScaleMerge::RefineDecay(int n_groups) { return segments.empty() ? static_cast(o.image_number) : frame_dose[o.frame] + (o.image_number - static_cast(o.frame)); }; + // s^2 about the frame's mean (FrameMeanS2): the per-frame G has the frame's average already. + std::vector frame_s2; + auto s2c = [&](const auto &o) { return s2_of(o.d) - frame_s2[o.frame]; }; auto decay_factor = [&](const auto &o, double slope) { - return std::exp(slope * (dose(o) - fcenter) * s2_of(o.d)); + return std::exp(slope * (dose(o) - fcenter) * s2c(o)); }; // The fields the seven passes below read (three slope fits, four held-out scores), pulled out of the @@ -2413,6 +2432,7 @@ void RotationScaleMerge::RefineDecay(int n_groups) { decay_terms_kept_valid = false; if (!segments.empty()) MeasureSegmentDose(t, n_groups); + frame_s2 = FrameMeanS2(t); const int nt = static_cast(ThreadsForWork(t.term.size(), nthreads)); std::vector sw(n_groups), swI(n_groups); @@ -2440,7 +2460,7 @@ void RotationScaleMerge::RefineDecay(int n_groups) { const double Is = static_cast(o.I) * o.corr, sc = static_cast(o.sigma) * o.corr; if (!std::isfinite(Iref) || Iref <= 0.0 || !(Is > 0.0)) return; const double w = (Is / sc) * (Is / sc); - const double x = (dose(o) - fcenter) * s2_of(o.d), y = std::log(Iref / Is); + const double x = (dose(o) - fcenter) * s2c(o), y = std::log(Iref / Is); a[0] += w; a[1] += w * x; a[2] += w * y; a[3] += w * x * x; a[4] += w * x * y; }, [](Lin &a, const Lin &b) { for (int j = 0; j < 5; ++j) a[j] += b[j]; }); const double Sw = S[0], Sx = S[1], Sy = S[2], Sxx = S[3], Sxy = S[4]; @@ -2602,7 +2622,7 @@ void RotationScaleMerge::RefineDecay(int n_groups) { for (int i = lo; i < hi; ++i) { Obs &o = fulls[i]; if (!usable(o)) continue; - const double f = use_step ? std::exp(2.0 * (b[frame_segment[o.frame]] - b_mid) * s2_of(o.d)) + const double f = use_step ? std::exp(2.0 * (b[frame_segment[o.frame]] - b_mid) * s2c(o)) : decay_factor(o, slope); o.corr = static_cast(o.corr * f); } @@ -2767,12 +2787,14 @@ std::vector RotationScaleMerge::SolveCurvatureSmoothedB(const std::vecto return b; } -std::vector RotationScaleMerge::FitRelativeBCurve(const DecayTerms &t, int n_groups, int n_batch, - int frames_per_batch, int gparity) const { +std::vector RotationScaleMerge::FitRelativeBCurve(const DecayTerms &t, const std::vector &frame_s2, + int n_groups, int n_batch, int frames_per_batch, + int gparity) const { // Fit one relative-B per batch over the ASU-group subset {group&1 == gparity} (gparity < 0 = all fulls), // against an inverse-variance reference built from that same subset (no leakage). Per batch the model is - // y = ln(I_ref / I_obs) = b * s^2 through the origin (the resolution-flat intercept is the per-frame G, - // already applied), so the data term is b_c = sum(w s^2 y) / sum(w s^2 s^2); SolveCurvatureSmoothedB then + // y = ln(I_ref / I_obs) = b * (s^2 - _frame): the per-frame G already holds each frame's average, + // so b only tilts a frame about its own mean s^2 (FrameMeanS2), and the data term is + // b_c = sum(w s^2 y) / sum(w s^2 s^2) with s^2 taken about that mean; SolveCurvatureSmoothedB then // smooths it. Finally subtract the leverage-weighted mean: a constant B is a global Wilson-B degenerate // with overall scale, and cannot change equivalent agreement (within one ASU group every equivalent sits // at the same s^2, so only b VARYING between batches moves the merge). Drives the per-batch correction. @@ -2802,7 +2824,7 @@ std::vector RotationScaleMerge::FitRelativeBCurve(const DecayTerms &t, i const double Is = static_cast(o.I) * o.corr, sc = static_cast(o.sigma) * o.corr; if (!std::isfinite(Iref) || Iref <= 0.0 || !(Is > 0.0)) return; const double w = (Is / sc) * (Is / sc); - const double s2 = s2_of(o.d), y = std::log(Iref / Is); + const double s2 = s2_of(o.d) - frame_s2[o.frame], y = std::log(Iref / Is); a[0][batch_of(o)] += w * s2 * y; a[1][batch_of(o)] += w * s2 * s2; }, AddArrays<2>); const std::vector &num = nd[0], &den = nd[1]; @@ -4058,13 +4080,14 @@ void RotationScaleMerge::RefineRelativeB(int n_groups) { && o.partiality >= min_partiality; }; auto batch_of = [&](const auto &o) { return std::min(n_batch - 1, o.frame / frames_per_batch); }; - auto b_factor = [&](const auto &o, const std::vector &b) { - return std::exp(b[batch_of(o)] * s2_of(o.d)); - }; // The fields the three curve fits and the three held-out scores below read, pulled out of the fat // records once, with the group-ordered copy their per-group references run over (BuildDecayTerms). DecayTerms t; BuildDecayTerms(n_groups, t); + const std::vector frame_s2 = FrameMeanS2(t); + auto b_factor = [&](const auto &o, const std::vector &b) { + return std::exp(b[batch_of(o)] * (s2_of(o.d) - frame_s2[o.frame])); + }; const int nt = static_cast(ThreadsForWork(t.term.size(), nthreads)); std::vector sw(n_groups), swI(n_groups); // Held-out disagreement over the group subset {group&1 == gparity} with `b` applied: the same @@ -4100,7 +4123,7 @@ void RotationScaleMerge::RefineRelativeB(int n_groups) { // equivalents (same s^2, different batch) into extra scatter - net harmful, exactly like RefineDecay's // sub-floor slope. (RELATIVE_B_MIN_SPREAD ~ DECAY_MIN_DELTA_B.) constexpr double RELATIVE_B_MIN_SPREAD = 2.0; // A^2, minimum peak-to-peak relative-B to engage - const std::vector b_all = FitRelativeBCurve(t, n_groups, n_batch, frames_per_batch, -1); + const std::vector b_all = FitRelativeBCurve(t, frame_s2, n_groups, n_batch, frames_per_batch, -1); const double bmin = *std::min_element(b_all.begin(), b_all.end()); const double bmax = *std::max_element(b_all.begin(), b_all.end()); if (bmax - bmin < RELATIVE_B_MIN_SPREAD) { @@ -4112,8 +4135,8 @@ void RotationScaleMerge::RefineRelativeB(int n_groups) { // per-batch structure generalises across the equivalent split; over-fit per-batch noise does not. const std::vector zero(n_batch, 0.0); const double base = subset_disagreement(0, zero) + subset_disagreement(1, zero); - const std::vector b_even = FitRelativeBCurve(t, n_groups, n_batch, frames_per_batch, 0); - const std::vector b_odd = FitRelativeBCurve(t, n_groups, n_batch, frames_per_batch, 1); + const std::vector b_even = FitRelativeBCurve(t, frame_s2, n_groups, n_batch, frames_per_batch, 0); + const std::vector b_odd = FitRelativeBCurve(t, frame_s2, n_groups, n_batch, frames_per_batch, 1); const double gain = base - (subset_disagreement(1, b_even) + subset_disagreement(0, b_odd)); if (!(gain > CV_MIN_RELATIVE_GAIN * base)) { logger->Info("Relative-B: not cross-validated ({} batches, peak-to-peak {:.2f} A^2, held-out gain {:.1f}%, skipped)", diff --git a/image_analysis/scale_merge/RotationScaleMerge.h b/image_analysis/scale_merge/RotationScaleMerge.h index 0671bf5e4..fa849d68c 100644 --- a/image_analysis/scale_merge/RotationScaleMerge.h +++ b/image_analysis/scale_merge/RotationScaleMerge.h @@ -1043,8 +1043,12 @@ private: // Fit a smoothed per-batch relative-B curve (A^2 per batch) on the fulls over the ASU-group subset // {group&1==gparity} (gparity<0 = all): the weighted s^2 slope of ln(Iref/Iobs) per batch against a // subset-global reference, smoothed and zero-mean-anchored. Drives the per-batch correction. - std::vector FitRelativeBCurve(const DecayTerms &t, int n_groups, int n_batch, - int frames_per_batch, int gparity) const; + std::vector FitRelativeBCurve(const DecayTerms &t, const std::vector &frame_s2, int n_groups, + int n_batch, int frames_per_batch, int gparity) const; + // Per frame, the mean s^2 = 1/(4 d^2) of its terms at the weights the per-frame G was fitted at, + // (I/sigma)^2. A relative B is applied about it: the frame's G already holds the frame's average + // scale, so exp(B s^2) alone would move that average a second time. + std::vector FrameMeanS2(const DecayTerms &t) const; // Radiation-damage MONITOR (report-only): measure the per-batch relative-B on the scaled fulls before // any decay correction and store the first->last relative-B change + the per-batch curve on this object // (copied into the result statistics by MergeAndStats, then printed / logged / written to the mmCIF). diff --git a/tests/RotationScaleMergeSegmentsTest.cpp b/tests/RotationScaleMergeSegmentsTest.cpp index 1a1957398..a24845b38 100644 --- a/tests/RotationScaleMergeSegmentsTest.cpp +++ b/tests/RotationScaleMergeSegmentsTest.cpp @@ -192,6 +192,27 @@ TEST_CASE("RotationScaleMergeSegments_DoseLinearDecayAcrossSweeps", "[RotationSc CHECK(r.segment_decay_model == "dose-linear"); } +TEST_CASE("RotationScaleMerge_DecayRampWithinOneSweep", "[RotationScale]") { + // One sweep whose B rises steadily from 0 to 10 A^2: the per-frame G takes each frame's average, the + // decay the tilt about it, so the high-resolution fulls come out on one scale from the first frame to + // the last. + auto data = MakeSweeps({{200, 1.0, 0.0, 10.0}}, 23); + const auto r = Merge(data, SyntheticExperiment(true), {}, true); + auto ratio = [&](int f0, int f1) { + std::vector v; + for (const auto &o: r.scaled_fulls) { + const double t = data.I_true.at(FriedelKey(o.h, o.k, o.l)); + if (o.image_number >= static_cast(f0) && o.image_number < static_cast(f1) + && o.d < 2.2f && t > 200.0) + v.push_back(o.I / t); + } + REQUIRE(v.size() > 20); + std::nth_element(v.begin(), v.begin() + v.size() / 2, v.end()); + return v[v.size() / 2]; + }; + CHECK(ratio(170, 200) / ratio(0, 30) == Catch::Approx(1.0).epsilon(0.08)); +} + TEST_CASE("RotationScaleMergeSegments_SegmentsMustCoverTheFrames", "[RotationScale]") { const std::vector sweeps{{10, 1.0, 0.0}, {10, 1.0, 0.0}}; auto data = MakeSweeps(sweeps, 13); @@ -228,7 +249,7 @@ TEST_CASE("RotationScaleMergeSegments_NoSegmentsIsTheEngineAsBefore", "[Rotation if (!on_gpu) CHECK(hash == 15900277682318835699ULL); else if (get_gpu_description().find("RTX 5080") != std::string::npos) - CHECK(hash == 6640579017825061097ULL); + CHECK(hash == 1680029721518244960ULL); } TEST_CASE("RotationScaleMerge_ShadowDoesNotBendTheResolutionShape", "[RotationScale]") { @@ -325,6 +346,13 @@ TEST_CASE("RotationScaleMerge_SecondCrystalStretchRemovedWhole", "[RotationScale r.image_number += 600.0f; data.frames.push_back(std::move(o)); } + // A 3% error proportional to the intensity, as every real measurement has: without it the error + // model's b is not resolved, and the merge is taken from the fulls alone, which this test is not about. + std::mt19937 rng(24); + std::normal_distribution noise(0.0, 1.0); + for (auto &o: data.frames) + for (auto &r: o.reflections) + r.I *= static_cast(1.0 + 0.03 * noise(rng)); const auto r = Merge(data, SyntheticExperiment(true), {}); const auto &sq = r.statistics.sweep_quality; const auto &removed = sq.removed_stretches; -- 2.54.1 From fffc07b894c010f8514576fbf07aef8a8f5e4d89 Mon Sep 17 00:00:00 2001 From: Filip Leonarski Date: Sat, 14 Nov 2026 01:00:04 +0100 Subject: [PATCH 005/229] tNCS analysis: sort keys read from arrays of their own The modulation band's sort of every acentric reflection, and the class ladder's two sorts, compared fields read from whole MergedReflections - a cache miss per comparison on a large merge, serial, and the largest single cost left in the pre-promotion analysis on a P1 merge of a large cell. The keys are now copied into arrays first; the comparisons and so the orders are unchanged. 4nwv (I222, offline, --no-refine): pre-promotion analyses wait 1.9-3.4 s -> 0.0-0.1 s, report identical. [tncs] tests pass. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01HVeDQsU5a8AJUdJPgWevAK --- .../scale_merge/TranslationalNCS.cpp | 22 +++++++++++++------ 1 file changed, 15 insertions(+), 7 deletions(-) diff --git a/image_analysis/scale_merge/TranslationalNCS.cpp b/image_analysis/scale_merge/TranslationalNCS.cpp index f76e569d9..2acb83aee 100644 --- a/image_analysis/scale_merge/TranslationalNCS.cpp +++ b/image_analysis/scale_merge/TranslationalNCS.cpp @@ -535,8 +535,12 @@ TranslationalNCSResult AnalyzeTranslationalNCS(const std::vector(i)); } - std::sort(mod_idx.begin(), mod_idx.end(), - [&](int a, int b) { return merged[a].d != merged[b].d ? merged[a].d > merged[b].d : a < b; }); + // the comparisons read d from an array of its own rather than each from a whole MergedReflection: + // this sort, of every acentric reflection, was most of the analysis' serial time on a large merge + std::vector d(merged.size()); + for (int i : mod_idx) + d[i] = merged[i].d; + std::sort(mod_idx.begin(), mod_idx.end(), [&](int a, int b) { return d[a] != d[b] ? d[a] > d[b] : a < b; }); const int n_beyond = static_cast(std::count_if(mod_idx.begin(), mod_idx.end(), [&](int i) { return merged[i].d >= kModulationDMin; })); mod_idx.resize(std::min(kMaxModulationBand, std::max(n_beyond, std::min(kMinModulationBand, @@ -864,12 +868,16 @@ TranslationalNCSResult AnalyzeTranslationalNCS(const std::vector(i)); // Equal-count shells sorted by |h|, so that every stage of the ladder reads a population // that is already normalised and can be taken as a prefix. - std::sort(idx.begin(), idx.end(), [&](int a, int b) { - return std::max({std::abs(merged[a].h), std::abs(merged[a].k), std::abs(merged[a].l)}) - < std::max({std::abs(merged[b].h), std::abs(merged[b].k), std::abs(merged[b].l)}); - }); + // the keys in arrays of their own, as the modulation band's sort above + std::vector order(merged.size()); + std::vector d(merged.size()); + for (int i : idx) { + order[i] = std::max({std::abs(merged[i].h), std::abs(merged[i].k), std::abs(merged[i].l)}); + d[i] = merged[i].d; + } + std::sort(idx.begin(), idx.end(), [&](int a, int b) { return order[a] < order[b]; }); std::vector by_d = idx; - std::sort(by_d.begin(), by_d.end(), [&](int a, int b) { return merged[a].d > merged[b].d; }); + std::sort(by_d.begin(), by_d.end(), [&](int a, int b) { return d[a] > d[b]; }); std::vector e2_of(merged.size(), std::numeric_limits::quiet_NaN()); const size_t n_shells = std::max(1, by_d.size() / 500); for (size_t s = 0; s < n_shells; ++s) { -- 2.54.1 From c1bbf02a7cb7ad4b5175db2cb501d47549d1bd76 Mon Sep 17 00:00:00 2001 From: Filip Leonarski Date: Sat, 14 Nov 2026 01:50:13 +0100 Subject: [PATCH 006/229] Live rotation integrates at the radius the spot width gives, as offline does The broker's live mode (and --fast-live) held r1 at the default 4 px because the starvation near-tie is re-checked on the whole sweep, which fast_live never does. Nothing else needs the whole sweep: the spot width is measured on the pre-scan frames and the crowding of the widened background rings is counted on the pre-pass frames, both available to the live run before its canonical pass. A near tie now simply stays where the pre-pass decided it, like every other fast-live decision. Simulated live (--simulate-live 10 --fast-live), before -> after, now equal to the offline run: 360 deg trigonal sweep (r1 4 -> 6): ISa 18.97 -> 20.44, d 1.730 -> 1.717 A, Wilson B 58.3 -> 54.6, reported relative-B over the sweep 15.6 -> 10.9 A^2 monoclinic sweep (r1 widened): d 1.652 -> 1.556 A, ISa 9.8 -> 11.3, R_meas 17.5 -> 16.8% two sets the width leaves at r1 4: unchanged wall time: no increase (30 vs 33 s, 19 vs 24 s, 22 vs 22 s on a shared GPU) Not a free win on every axis: on the trigonal sweep the r1 4 merge reads better against a model (R-free 0.3617 vs 0.3628, shell-scaled R 0.318 vs 0.323, Fe anomalous peaks +1.2 sigma each), and a 10-set battery with --integration-radius 4 forced offline splits the same way (R-free better on 5 of 8, anomalous peak height worse on 5 of 7, one set loses its space group). The radius rule itself is the open question; this commit only makes live and offline give the same answer. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01HVeDQsU5a8AJUdJPgWevAK --- docs/RUGNUX_CLI.md | 2 +- rugnux/RugnuxLive.cpp | 6 ++++-- rugnux/rugnux_cli.cpp | 2 -- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/RUGNUX_CLI.md b/docs/RUGNUX_CLI.md index 8c09f27c7..f263db765 100644 --- a/docs/RUGNUX_CLI.md +++ b/docs/RUGNUX_CLI.md @@ -162,7 +162,7 @@ With the input already on disk, the URL is ignored. | `-t, --stride ` | Process every *n*-th image (default: 1) | | `-v, --verbose` | Show the whole log on the terminal in place of the steps; `_log.txt` is written either way | | `--simulate-live ` | Read a stored input as the collection it was while being written: image *i* becomes readable (*i*+1)·`ms` ms after the start (0: all at once). The run takes the live path a broker URL takes, with the same result; for testing the live workflow without a broker. `--mode mx` only | -| `--fast-live` | With `--simulate-live` or a broker URL: run as the broker's rugnux live mode does — every decision stands where it was first taken, nothing is re-checked or run again once the sweep is in, the integration radius is fixed, and SIGINT cuts the run to what it has established. A difficult crystal can come out worse | +| `--fast-live` | With `--simulate-live` or a broker URL: run as the broker's rugnux live mode does — every decision stands where it was first taken, nothing is re-checked or run again once the sweep is in (the integration radius from the spot width stays where the pre-pass frames put it), and SIGINT cuts the run to what it has established. A difficult crystal can come out worse | | `--sweeps joint\|separate` | Several rotation sweeps (see Inputs): `joint` (the default) merges them as one dataset into `.*`; `separate` processes each alone into `_s_*` | | `--no-gpu` | Run on the CPU only, as on a machine without a GPU, even where one is present: CUDA is not touched (nor, on macOS, the Apple GPU that Bragg integration, the model density and the molecular-replacement rotation function otherwise run on) and every GPU step takes its CPU path (`-X FFT` indexes with FFTW and `-X FFBIDX` with its CPU implementation; `-X cuFFT` is refused) | diff --git a/rugnux/RugnuxLive.cpp b/rugnux/RugnuxLive.cpp index 1732e781c..ec93ee2e3 100644 --- a/rugnux/RugnuxLive.cpp +++ b/rugnux/RugnuxLive.cpp @@ -59,8 +59,10 @@ RugnuxLiveSetup MakeRugnuxLiveSetup(const JFJochReaderDataset &dataset, int nthr c.refine = true; c.live = true; c.fast_live = true; - // Decided late, on the whole sweep, as it re-checks its radius there - which fast_live does not. - c.adaptive_integration_radius = false; + // The signal radius from the spot width of the pre-scan frames, as in `rugnux`; where the pre-pass + // counts the widened radius crowding the background rings the canonical pass keeps the default, and + // a near tie stays where it was decided (fast_live re-checks nothing on the whole sweep). + c.adaptive_integration_radius = true; return s; } diff --git a/rugnux/rugnux_cli.cpp b/rugnux/rugnux_cli.cpp index 1f113a7ed..5d1cb6a2a 100644 --- a/rugnux/rugnux_cli.cpp +++ b/rugnux/rugnux_cli.cpp @@ -3723,8 +3723,6 @@ int RugnuxInputRun::PrepareRugnuxInput() { config.finalist_ledger = finalist_ledger_flag; config.live = broker_feed || simulate_live; config.fast_live = fast_live && config.live; - if (config.fast_live) - config.adaptive_integration_radius = false; // as MakeRugnuxLiveSetup if (simulate_live) logger.Info("Simulated live collection: image i readable (i+1) x {:.1f} ms after the run starts", simulated_frame_time.count() / 1000.0); -- 2.54.1 From 8c023fd8262f3f09032d2fc6d4e99e9d64cefdd3 Mon Sep 17 00:00:00 2001 From: Filip Leonarski Date: Sat, 14 Nov 2026 01:51:14 +0100 Subject: [PATCH 007/229] Radiation-damage caution no longer claims a decay correction that did not happen The anisotropy caution for a run with more than 10 A^2 of relative B said the scale model removes the average monotone damage and advised --relative-b. The decay is applied only where it cross-validates, and on the rotation battery it never did (every damaged set skipped it), so the sentence was false wherever it was printed; --relative-b on such a run (a 360 deg trigonal sweep, +11 A^2) is itself refused by its cross-validation, and forced it lowers ISa 20.4 -> 18.6 and CC_anom 0.45 -> 0.33. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01HVeDQsU5a8AJUdJPgWevAK --- image_analysis/scale_merge/AnisotropyAnalysis.cpp | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/image_analysis/scale_merge/AnisotropyAnalysis.cpp b/image_analysis/scale_merge/AnisotropyAnalysis.cpp index 9da2c1ba0..5896281d8 100644 --- a/image_analysis/scale_merge/AnisotropyAnalysis.cpp +++ b/image_analysis/scale_merge/AnisotropyAnalysis.cpp @@ -1470,8 +1470,8 @@ AnisotropyResult AnalyzeAnisotropy(const std::vector &merged, "reachable by a lab-fixed systematic and reduces the power of the test"); if (std::isfinite(run.radiation_damage_relative_b) && std::fabs(run.radiation_damage_relative_b) > 10.0) result.cautions.emplace_back( - "the run carries substantial radiation damage; the scale model removes its average " - "monotone part, but a non-monotone dose ramp needs --relative-b to be taken out too"); + "the run carries substantial radiation damage; the scale model takes out a decay only " + "where it cross-validates, so part of the damage can remain in the fall-off"); // R2's Laue-class caution, fired on its measured signature rather than on the Laue class alone. // Too high a symmetry assignment pushes real anisotropy into the directions the systematic error is // measured in, so sigma_sys is inflated by the signal itself and the gate collapses (measured: a -- 2.54.1 From fabcb0e4d3a1a284213791ba07e6ad713bbaee14 Mon Sep 17 00:00:00 2001 From: Filip Leonarski Date: Fri, 13 Nov 2026 23:51:02 +0100 Subject: [PATCH 008/229] Refinement: run again from the refined model while R-free falls (3 rounds at most) One refinement chooses its X-ray weight and NCS on the B factors as given and its displacement model (TLS / U) only after them. Where the displacements change much - a placed prediction, whose B factors are its pLDDT - the weights stand on B factors the model no longer has. Running the refinement again from its own result (as REFMAC users do by hand) lets the weight ladder and the NCS choice see the refined displacements. Cytochrome C, three copies placed by MR from the AlphaFold model, 1.73 A, live merge: round 2 chose an eight times lower X-ray weight without NCS, R-work 0.367 -> 0.361 at bonds 0.002 -> 0.001 A, R-free 0.418 -> 0.405; with --refine-solvent 0.427 -> 0.409 -> 0.401. REFMAC5 from the same model reaches 0.41-0.43. On 22 battery merges with their placed models no R-free rose; lyso_x06da_ref -0.003, cytc_x10sa -0.005, 9khr -0.003, 6hv2 -0.002, the rest unchanged. End to end from the AlphaFold DB models of the timing benchmark (MR, rugnux mx): myob_x10sa 0.341 -> 0.312, cytc_x10sa 0.419 -> 0.410, 9zlo 0.289 -> 0.283, 9s02 and 9gjx unchanged. Cost: refinement time x1.3-4 (cytochrome C 6 -> 12 s on the GPU; 9s02 22 -> 30 s), the second round being run to be judged. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01HVeDQsU5a8AJUdJPgWevAK --- .../structure_refinement/Refinement.cpp | 59 +++++++++++++++++-- 1 file changed, 55 insertions(+), 4 deletions(-) diff --git a/image_analysis/structure_refinement/Refinement.cpp b/image_analysis/structure_refinement/Refinement.cpp index cb1e3406e..7e8c81502 100644 --- a/image_analysis/structure_refinement/Refinement.cpp +++ b/image_analysis/structure_refinement/Refinement.cpp @@ -3332,6 +3332,57 @@ double FinalRWork(const RefinementResult &r) { return r.restrained ? r.r_work : r.r_work_placement; } +// The refinement run again from the model it ended with, while that lowers R-free by more than the tie, up to +// REFINEMENT_ROUNDS in all. One refinement chooses its weights on the B factors as given and its displacement model +// only after them, so where the displacements change much - a placed prediction, whose B factors are its pLDDT - the +// weights were chosen for B factors it no longer has: on a placed prediction of three copies the second round chose +// an eight times lower X-ray weight, R-work and R-free both fell and R-free went 0.418 -> 0.405 (with the solvent +// build 0.427 -> 0.409 -> 0.401), where REFMAC5 reached 0.41-0.43 from the same model. The first round's view of +// the model as given is kept; the solvent build is the first round's. +constexpr int REFINEMENT_ROUNDS = 3; + +RefinementResult RefineRounds(const gemmi::Structure &placed, const std::vector &merged, + const gemmi::UnitCell &cell, const gemmi::SpaceGroup &sg, double wavelength_A, + Logger &logger, const RefinementSettings &settings, + const std::vector &twin_laws = {}, size_t null_first = 0, + CardHeld *held = nullptr) { + RefinementResult result = RefineOnce(placed, merged, cell, sg, wavelength_A, logger, settings, twin_laws, + null_first, held); + RefinementSettings again = settings; + again.solvent = false; + for (int round = 2; round <= REFINEMENT_ROUNDS; round++) { + if (!result.ok || !result.restrained || result.as_given || result.cancelled || settings.score_only || + result.model == nullptr) + break; + logger.Info("Refinement, round {}: from the model the round before ended with (R-free {:.4f})", round, + result.r_free); + RefinementResult next = RefineOnce(*result.model, merged, cell, sg, wavelength_A, logger, again, twin_laws, + null_first); + if (!next.ok || !next.restrained || next.as_given || !(next.r_free < result.r_free - R_FREE_TIE)) { + logger.Info("Refinement, round {}: not kept (R-free {:.4f})", round, FinalRFree(next)); + result.seconds += next.seconds; + break; + } + next.seconds += result.seconds; + next.r_work_start = result.r_work_start; + next.r_free_start = result.r_free_start; + next.score_start = result.score_start; + next.adp_input = result.adp_input; + next.adp_input_aniso_atoms = result.adp_input_aniso_atoms; + next.rigid_bodies = result.rigid_bodies; + next.group_b = result.group_b; + next.r_work_placement = result.r_work_placement; + next.r_free_placement = result.r_free_placement; + next.geometry_start = result.geometry_start; + next.ncs_rmsd_start = result.ncs_rmsd_start; + next.solvent_build = result.solvent_build; + if (next.adp_model == "the model's U held") // the round before's displacement model, refined on + next.adp_model = result.adp_model; + result = std::move(next); + } + return result; +} + // The twin hypotheses beside the untwinned refinement `result`, as a ladder. First one law: the placed model refined // again, solvent build and displacement model included, against the data as twinned by a law of the lattice, and the // twinned refinement taken (into `result`) where the law beats its own null (TwinNull) on the free reflections by @@ -3407,7 +3458,7 @@ void DecideTwin(const gemmi::Structure &placed, const std::vector kept{law}; @@ -3590,7 +3641,7 @@ RefinementResult RefineModel(const gemmi::Structure &placed, const std::vector Date: Sat, 14 Nov 2026 03:24:01 +0100 Subject: [PATCH 009/229] Refinement rounds: no placement in rounds 2-3, no maps for a round not kept A further round starts from the model the round before refined, so the rigid-body and per-residue-B placement is skipped there; and a round whose R-free does not beat the one before is returned before its maps, twin null and blobs (it is discarded anyway). The placement skip changes the path of the later rounds, not the rule: on 22 battery merges with their placed models R-free equal to the rounds without it except lyso_x06da_ref 0.2413 -> 0.2430 and cytc_x06da_1 0.3143 -> 0.3128; from the timing benchmark's AlphaFold models (MR, mx): cytc_x10sa 0.410 -> 0.399, 9zlo 0.283 -> 0.284, myob_x10sa 0.312 -> 0.312, 9s02/9gjx equal; cytochrome C live merge, MR model 0.405 -> 0.400. Saves about 1-2 s of the 7-8 s the rounds add on cytochrome C (wall 15.5 -> 13.6 s). Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01HVeDQsU5a8AJUdJPgWevAK --- image_analysis/structure_refinement/Refinement.cpp | 11 ++++++++++- image_analysis/structure_refinement/Refinement.h | 4 ++++ 2 files changed, 14 insertions(+), 1 deletion(-) diff --git a/image_analysis/structure_refinement/Refinement.cpp b/image_analysis/structure_refinement/Refinement.cpp index 7e8c81502..9db12da54 100644 --- a/image_analysis/structure_refinement/Refinement.cpp +++ b/image_analysis/structure_refinement/Refinement.cpp @@ -2563,7 +2563,8 @@ RefinementResult RefineOnce(const gemmi::Structure &placed, const std::vector(std::chrono::steady_clock::now() - start).count(); + return result; + } finish(); logger.Info("Refinement: done in {:.1f} s, {} target evaluations{}", result.seconds, ctx.evaluations, @@ -3350,12 +3357,14 @@ RefinementResult RefineRounds(const gemmi::Structure &placed, const std::vector< null_first, held); RefinementSettings again = settings; again.solvent = false; + again.placement = false; // the chains and the B per residue were placed by the first round for (int round = 2; round <= REFINEMENT_ROUNDS; round++) { if (!result.ok || !result.restrained || result.as_given || result.cancelled || settings.score_only || result.model == nullptr) break; logger.Info("Refinement, round {}: from the model the round before ended with (R-free {:.4f})", round, result.r_free); + again.keep_below = result.r_free - R_FREE_TIE; RefinementResult next = RefineOnce(*result.model, merged, cell, sg, wavelength_A, logger, again, twin_laws, null_first); if (!next.ok || !next.restrained || next.as_given || !(next.r_free < result.r_free - R_FREE_TIE)) { diff --git a/image_analysis/structure_refinement/Refinement.h b/image_analysis/structure_refinement/Refinement.h index c10e6dd84..c5b46c787 100644 --- a/image_analysis/structure_refinement/Refinement.h +++ b/image_analysis/structure_refinement/Refinement.h @@ -84,6 +84,10 @@ struct RefinementSettings { // statistic - false where the model has most likely been refined against the free reflections too (a deposited // model of this crystal scored on a free set drawn here). bool as_given_competes = true; + // For a further round of the refinement (RefineRounds): the placement stage skipped, and the maps, the twin null + // and the blobs made only where R-free ends below keep_below - the round is not kept otherwise. + bool placement = true; + double keep_below = INFINITY; bool gpu = true; size_t nthreads = 1; size_t gpu_resident_bytes = 0; // held on the card by what runs beside -- 2.54.1 From 5a959bf36498ae42587d1b0d3221e62044941fef Mon Sep 17 00:00:00 2001 From: Filip Leonarski Date: Fri, 13 Nov 2026 23:28:29 +0100 Subject: [PATCH 010/229] rugnux live: the merge's numbers at the scaling checkpoint, not after the model work A rotation run published its space group, resolution, ISa and shell table only when the whole run was over, so the live page showed dashes through molecular replacement and refinement although the merge had long been made. RugnuxObserver gets OnMerge, called on the pass that makes the result once its merge is made (before the "Analyses" step); the rotation receiver publishes the headline and the shell table there, and again at the end as before (with the model's R-free by shell, and a model can still change the hand). The API descriptions say so; the generated clients carry the new words only. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01HVeDQsU5a8AJUdJPgWevAK --- broker/gen/model/Rugnux_live_status.h | 8 ++--- broker/jfjoch_api.yaml | 9 +++--- broker/redoc-static.html | 2 +- docs/python_client/docs/RugnuxLiveShell.md | 2 +- docs/python_client/docs/RugnuxLiveStatus.md | 8 ++--- frontend/src/client/types.gen.ts | 9 +++--- receiver/JFJochReceiverRugnuxRotation.cpp | 35 +++++++++++++-------- rugnux/Rugnux.h | 4 +++ rugnux/RugnuxScaleMerge.cpp | 2 ++ 9 files changed, 48 insertions(+), 31 deletions(-) diff --git a/broker/gen/model/Rugnux_live_status.h b/broker/gen/model/Rugnux_live_status.h index 4bb87eb98..790a8be63 100644 --- a/broker/gen/model/Rugnux_live_status.h +++ b/broker/gen/model/Rugnux_live_status.h @@ -113,7 +113,7 @@ public: bool shellsMergeIsSet() const; void unsetShells_merge(); /// - /// Merging statistics by resolution shell of the latest merge, coarse to fine, as the shell table of `_report.txt`. Rotation: once the run is over; serial: at each provisional merge and at the end. `overall` is the same table's \"Overall\" row (whole-merge completeness, multiplicity, I/sigma, CC1/2, R_meas or R_split, CCref, and the R-free of the final model - refined where rugnux refined it, as `model.refinement.r_free`, else as placed, as `model.r_free`), present with `shells`. + /// Merging statistics by resolution shell of the latest merge, coarse to fine, as the shell table of `_report.txt`. Rotation: once the collection is scaled and merged (before the model work), again at the end; serial: at each provisional merge and at the end. `overall` is the same table's \"Overall\" row (whole-merge completeness, multiplicity, I/sigma, CC1/2, R_meas or R_split, CCref, and the R-free of the final model - refined where rugnux refined it, as `model.refinement.r_free`, else as placed, as `model.r_free`), present with `shells`. /// std::vector getShells() const; void setShells(std::vector const& value); @@ -141,21 +141,21 @@ public: bool frameRangesIsSet() const; void unsetFrame_ranges(); /// - /// Space group of the result (the summary's \"Space group\" row); absent until the run is over + /// Space group of the result (the summary's \"Space group\" row); absent until the collection is scaled and merged /// std::string getSpaceGroup() const; void setSpaceGroup(std::string const& value); bool spaceGroupIsSet() const; void unsetSpace_group(); /// - /// High-resolution limit of the merge, in Angstrom; absent until the run is over, or without a merge + /// High-resolution limit of the merge, in Angstrom; absent until the collection is scaled and merged, or without a merge /// double getDMin() const; void setDMin(double const value); bool dMinIsSet() const; void unsetD_min(); /// - /// ISa of the error model; absent until the run is over, or where it was not determined + /// ISa of the error model; absent until the collection is scaled and merged, or where it was not determined /// double getIsa() const; void setIsa(double const value); diff --git a/broker/jfjoch_api.yaml b/broker/jfjoch_api.yaml index a7464ef6e..39ebc40c0 100644 --- a/broker/jfjoch_api.yaml +++ b/broker/jfjoch_api.yaml @@ -3344,7 +3344,8 @@ components: type: array description: | Merging statistics by resolution shell of the latest merge, coarse to fine, as the shell table of - `_report.txt`. Rotation: once the run is over; serial: at each provisional merge and at the end. + `_report.txt`. Rotation: once the collection is scaled and merged (before the model work), again at + the end; serial: at each provisional merge and at the end. `overall` is the same table's "Overall" row (whole-merge completeness, multiplicity, I/sigma, CC1/2, R_meas or R_split, CCref, and the R-free of the final model - refined where rugnux refined it, as `model.refinement.r_free`, else as placed, as `model.r_free`), present with `shells`. @@ -3371,15 +3372,15 @@ components: $ref: '#/components/schemas/rugnux_live_frame_range' space_group: type: string - description: Space group of the result (the summary's "Space group" row); absent until the run is over + description: Space group of the result (the summary's "Space group" row); absent until the collection is scaled and merged d_min: type: number format: double - description: High-resolution limit of the merge, in Angstrom; absent until the run is over, or without a merge + description: High-resolution limit of the merge, in Angstrom; absent until the collection is scaled and merged, or without a merge isa: type: number format: double - description: ISa of the error model; absent until the run is over, or where it was not determined + description: ISa of the error model; absent until the collection is scaled and merged, or where it was not determined probe: type: string description: Answer of the early lattice probe on the first 60 degrees; empty until it answers, and the run's own lattice once the run has indexed diff --git a/broker/redoc-static.html b/broker/redoc-static.html index 016f2833b..8c3a392f3 100644 --- a/broker/redoc-static.html +++ b/broker/redoc-static.html @@ -1157,7 +1157,7 @@ then image might be replaced in the buffer between calling /images and /image.cb
- -

Jungfraujoch (1.0.0-rc.186)

Download OpenAPI specification:

Filip Leonarski (Paul Scherrer Institute): filip.leonarski@psi.ch License: GPL-3.0

API to control Jungfraujoch developed by the Paul Scherrer Institute (Switzerland). -Jungfraujoch is a data acquisition and analysis system for pixel array detectors, primarly PSI JUNGFRAU. -Jungfraujoch uses FPGA boards to acquire data at high data rates.

-

License Clarification

While this API definition is licensed under GPL-3.0, the GPL copyleft provisions do not apply -when this file is used solely to generate OpenAPI clients or when implementing applications that -interact with the API. Generated client code and applications using this API definition are not -subject to the GPL license requirements and may be distributed under terms of your choosing.

-

This exception is similar in spirit to the Linux Kernel's approach to userspace API headers and -the GCC Runtime Library Exception. The Linux Kernel developers have explicitly stated that -user programs that merely use the kernel interfaces (syscalls, ioctl definitions, etc.) are not -derivative works of the kernel and are not subject to the terms of the GPL.

-

This exception is intended to allow wider use of this API specification without imposing GPL -requirements on applications that merely interact with the API, regardless of whether they -communicate through network calls or other mechanisms.

-

Initialize detector and data acquisition

Should be used in two cases:

-
    -
  • Detector is in Inactive state
  • -
  • Detector is in Error state -X-ray shutter must be closed. -This operation will reconfigure network interface of the detector. -During operation of the detector it is recommended to use the POST /pedestal operation instead. -If storage cells are used, the execution time might be few minutes. -It also clears the image buffer, the previous collection's plots and live rugnux status, disables live rugnux analysis and removes the rugnux model. -It drops the previous dataset's bearer tokens and resets its settings, so nothing of that dataset stays readable.
  • -
-

This is async function - one needs to use POST /wait_till_done to ensure operation is done.

-

Responses

Response samples

Content type
application/json
{
  • "msg": "Detector in wrong state",
  • "reason": "WrongDAQState"
}

Collect dark current for the detector

Updates calibration of the JUNGFRAU detector. Must be in Idle state.

-

X-ray shutter must be closed. Recommended to run once per hour for long integration times (> 100 us).

-

This is async function - one needs to use POST /wait_till_done to ensure operation is done.

-

Responses

Response samples

Content type
application/json
{
  • "msg": "Detector in wrong state",
  • "reason": "WrongDAQState"
}

Start detector

Start data acquisition. -Detector must be in Idle state. -Default behavior is for the call to block until detector is ready to accept soft/TTL triggers. -However, this behavior can be changed by settings async_start to true in the request body, -in which case the call will return immediately and one needs to use /wait_until_running to ensure detector is ready to run. -Optional tokens protect the dataset: while set, its statistics, buffered images and plots -require Authorization: Bearer <token>.

-
Request Body schema: application/json
images_per_trigger
integer <int64> >= 1
Default: 1

For standard synchrotron data collection - this is number of images collected per one TTL trigger -For XFEL (pulsed source) - this number is ignored and set to 1 -For storage cell mode - this number is ignored and set to number of storage cells

-
ntrigger
integer <int64> >= 1
Default: 1

Number of TTL trigger that the detector is expected to receive during data collection

-
image_time_us
integer <int64> >= 0

Image time. -If not provided (or zero value) the frame time is assumed as default. -For JUNGFRAU image time must be multiple of frame time and max value is 256 * frame_time.
In XFEL mode: summation happens for frames collected with multiple triggers. -Ignored for storage cells and if raw data are saved.

-
beam_x_pxl
required
number <float>

/entry/detector/beam_center_x in NXmx -Beam center in X direction [pixels]

-
beam_y_pxl
required
number <float>

/entry/detector/beam_center_y in NXmx -Beam center in X direction [pixels]

-
detector_distance_mm
required
number <float> >= 0

/entry/detector/distance in NXmx Detector distance [mm]

-
incident_energy_keV
required
number <float> [ 0.001 .. 500 ]

Used to calculate /entry/beam/incident_wavelength in NXmx -Incident particle (photon, electron) energy in keV

-
file_prefix
string
Default: ""

Prefix for filenames. If left empty, no file will be saved.

-
images_per_file
integer <int64> >= 1

Number of images in a single HDF5 data file, taken literally when given. -If omitted, it is chosen from the acquisition: a rotation sweep of at most 20000 images -goes into a single data file, so the dataset stays readable by programs that follow only -the first data file of a legacy master; a grid scan is split on a whole number of fast-axis -rows; anything else (stills, serial) uses 1000.

-
space_group_number
integer <int64> [ 1 .. 230 ]

Number of space group for the crystal. Currently used solely as metadata, not relevant for image processing done in Jungfraujoch.

-
sample_name
string
Default: ""

/entry/sample/name in NXmx -Sample name

-
compression
string
Default: "bslz4"
Enum: "bslz4" "bszstd" "bszstd_rle" "bszstd_rlehuf" "none"

Compression type for the images transferred over ZeroMQ and saved to HDF5 file.

-
total_flux
number <float> >= 0

/entry/beam/total_flux in NXmx -Flux incident on beam plane in photons per second. In other words this is the flux integrated over area. [photons/s]

-
transmission
number <float> [ 0 .. 1 ]

/entry/instrument/attenuator/attenuator_transmission -Transmission of attenuator (filter) [no units]

-
beam_size_x_um
number <float> >= 0

First element of /entry/instrument/beam/incident_beam_size in NXmx -Horizontal size of the X-ray beam where it meets the sample - the FWHM of a focused beam, -the full width of a slit-defined one. [um]

-
beam_size_y_um
number <float> >= 0

Second element of /entry/instrument/beam/incident_beam_size in NXmx -Vertical size of the X-ray beam where it meets the sample. [um]

-
object (rotation_axis)

Definition of a crystal rotation axis

-
object (grid_scan)

Definition of a grid scan. Combine it with a goniometer axis to state the angle the spindle -stood at: send goniometer with step 0 and the start angle of the grid scan, and that -angle is written per image into the NXmx sample transformation chain. Without one the -spindle is recorded at 0, which says that nobody stated an angle rather than that the -spindle stood at 0.

-
header_appendix
any

Header appendix, added as user_data/user to start ZeroMQ message (can be any valid JSON) -In general, it is not saved in HDF5 file.

-

However, if values are placed in "hdf5" object, jfjoch_writer will write them in /entry/user of the HDF5 file. -This applies solely to string and number (double floating-point). No arrays/sub-objects is allowed. -For example {"hdf5": {"val1":1, "val2":"xyz"}}, will write /entry/user/val1 and /entry/user/val2.

-
image_appendix
any

Image appendix, added as user_data to image ZeroMQ message (can be any valid JSON) -Not saved in HDF5 file

-
data_reduction_factor_serialmx
number <float> [ 0 .. 1 ]
Default: 1

Rate at which non-indexed images are accepted to be forwarded to writer. -Value of 1.0 (default) means that all images are written. -Values below zero mean that non-indexed images will be accepted with a given probability.

-
pixel_value_low_threshold
integer <int64> >= 0

Set all counts lower than the value to zero. -When the value is set, negative numbers other than error pixel value are always set to zero. -Setting to zero is equivalent to turning the option off.

-
run_number
integer <int64> >= 0

Number of run within an experimental session. -Transferred over CBOR stream as "series ID", though not saved in HDF5 file. -It is highly recommended to keep this number unique for each data collection during experimental series. -If not provided, the number will be automatically incremented.

-
run_name
string

Unique ID of run. -Transferred over CBOR stream as "unique series ID", though not saved in HDF5 file. -It is highly recommended to keep this name unique for each data collection during experimental series. -If not provided, the name will be automatically generated as number + colon + file_prefix.

-
experiment_group
string

Name of group owning the data (e.g. p-group or proposal number). -Transferred over CBOR stream, though not saved in HDF5 file.

-
poisson_compression
integer <int64> [ 0 .. 16 ]

Enable lossy compression of pixel values that preserves Poisson statistics. -Requires to provide a numerical factor SQ. -Pixel value P will be transformed to round(sqrt(P) * SQ), with rounding to the closest integer. -Compression is turned off if the value is missing or it is set to zero.

-
write_nxmx_hdf5_master
boolean
Default: true

Write NXmx formatted HDF5 master file. Recommended to use for macromolecular crystallography experiments -and to turn off for other experiments.

-
save_calibration
boolean

Forward image calibration (at the moment pedestal and pedestal RMS for JUNGFRAU) using the ZeroMQ stream to writer. -If parameter is not provided calibration will be saved only if more than 4 images are recorded.

-
polarization_factor
number <float> [ -1 .. 1 ]

Polarization factor for integration; 1.0 is horizontal polarization; -1.0 is vertical polarization

-
ring_current_mA
number <float> >= 0

Ring current at the beginning of the data collection

-
sample_temperature_K
number <float> >= 0

Sample temperature in Kelvin

-
poni_rot1_rad
number <float> [ -6.28318530718 .. 6.28318530718 ]
Default: 0

PONI angle rot1 (see PyFAI documentation for details) in radians

-
poni_rot2_rad
number <float> [ -6.28318530718 .. 6.28318530718 ]
Default: 0

PONI angle rot2 (see PyFAI documentation for details) in radians

-
poni_rot3_rad
number <float> [ -6.28318530718 .. 6.28318530718 ]
Default: 0

PONI angle rot3 (see PyFAI documentation for details) in radians

-
object (unit_cell)

Unit cell parameters. Necessary to run indexing. Units of angstrom and degree

-
spot_finding
boolean
Default: true

Enable spot finding and save spots

-
object

Geometry of Smargon goniometer at SLS 2.0 / MX beamlines. -Assuming that Smargon is used as static positioner and not moving during the scan, allowing to reconstruct geometry.

-
max_spot_count
integer [ 10 .. 2000 ]
Default: 250

Maximum number of spots that are saved/used for indexing; spots with highest intensity are selected

-
detect_ice_rings
boolean

Flag spots as ice rings and reduce their effect on indexing. Left out, the broker's own -spot finding treats no spot as an ice ring, rugnux live decides as a bare rugnux would (on -for a rotation sweep, off for stills), and the master file carries no detect_ice_rings.

-
async_start
boolean
Default: false

When set to true, /start will not wait for detector and Jungfraujoch to be ready for the measurement.

-
Array of objects (detector_module_placement)

Where the detector's modules lie for this dataset, as rugnux measures them: rugnux writes -<prefix>_module_placement.json, which holds exactly this field, to be merged into the dataset settings. -Each entry names its module by its readout pixel 0 and readout axes in the stored image (x0, y0, -fast_axis, slow_axis, after mirror_y; see detector_module_placement), in any order; every -module must be named once, and only modules of the detector, else /start fails with 400. The image -is assembled as configured (custom_geometry); the placement goes into the start message and the -NXmx module_NN groups, and the analysis takes it. Omitted or empty: -modules as assembled.

-
tokens
Array of strings[ items non-empty ]

Bearer tokens that protect this dataset: any number, all equivalent (e.g. a beamline -secret and a dataset-specific user secret). While set, the endpoints marked with the -bearerAuth security scheme require Authorization: Bearer <token> and answer 401 otherwise. -Every accepted /start replaces the previous dataset's tokens; omitted or empty means no -protection. Never returned by any endpoint.

-
object

Responses

Request samples

Content type
application/json
{
  • "images_per_trigger": 1,
  • "ntrigger": 1,
  • "image_time_us": 0,
  • "beam_x_pxl": 0.1,
  • "beam_y_pxl": 0.1,
  • "detector_distance_mm": 0.1,
  • "incident_energy_keV": 0.001,
  • "file_prefix": "",
  • "images_per_file": 1,
  • "space_group_number": 1,
  • "sample_name": "",
  • "compression": "bslz4",
  • "total_flux": 0.1,
  • "transmission": 1,
  • "beam_size_x_um": 0.1,
  • "beam_size_y_um": 0.1,
  • "goniometer": {
    },
  • "grid_scan": {
    },
  • "header_appendix": null,
  • "image_appendix": null,
  • "data_reduction_factor_serialmx": 1,
  • "pixel_value_low_threshold": 0,
  • "run_number": 0,
  • "run_name": "string",
  • "experiment_group": "string",
  • "poisson_compression": 16,
  • "write_nxmx_hdf5_master": true,
  • "save_calibration": true,
  • "polarization_factor": -1,
  • "ring_current_mA": 0.1,
  • "sample_temperature_K": 0.1,
  • "poni_rot1_rad": 0,
  • "poni_rot2_rad": 0,
  • "poni_rot3_rad": 0,
  • "unit_cell": {
    },
  • "spot_finding": true,
  • "smargon": {
    },
  • "max_spot_count": 250,
  • "detect_ice_rings": true,
  • "async_start": false,
  • "module_placement": [
    ],
  • "tokens": [
    ],
  • "xray_fluorescence_spectrum": {
    }
}

Response samples

Content type
application/json
{
  • "msg": "Detector in wrong state",
  • "reason": "WrongDAQState"
}

Wait for acquisition running

Block execution of external script till detector and Jungfraujoch are ready to collect data. -To not block web server for a indefinite period of time, the procedure is provided with a timeout. -Extending timeout is possible, but requires to ensure safety that client will not close the connection and retry the connection.

-
query Parameters
timeout
integer [ 0 .. 3600 ]
Default: 60

Timeout in seconds (0 == immediate response)

-

Responses

Response samples

Content type
application/json
{
  • "msg": "Detector in wrong state",
  • "reason": "WrongDAQState"
}

Wait for acquisition done

Block execution of external script till initialization, data collection or pedestal is finished. -Running this command does not affect (cancel) running data collection, it is only to ensure synchronous execution of other software.

-

To not block web server for a indefinite period of time, the procedure is provided with a timeout. -Extending timeout is possible, but requires to ensure safety that client will not close the connection and retry the connection.

-
query Parameters
timeout
integer [ 0 .. 3600 ]
Default: 60

Timeout in seconds (0 == immediate response)

-

Responses

Response samples

Content type
application/json
{
  • "msg": "Detector in wrong state",
  • "reason": "WrongDAQState"
}

Send soft trigger to the detector

Generate soft trigger

-

Responses

Cancel running data collection

Command will inform FPGA network card to stop pedestal or data collection at the current stage. -Any frame that is currently being processed by CPU will be finished and sent to writer. -Given the command is making sure to gracefully stop data acquisition and detector, it might take some time to switch back after command finished to Idle state.

-

With rugnux live mode (/config/rugnux) the command also cuts the rugnux analysis, during the collection -or after its last image alike: the collection ends with what the analysis has established -(see cut in /rugnux/status). After the last image the collection itself is complete and is not -marked as cancelled.

-

If data collection is not running, the command has no effect.

-

Responses

Prepare detector to turn off

Should be in Idle or Error state. -Command deactivates data acquisition and turns off detector high voltage and ASIC. -Should be used always before turning off power from the detector.

-

Responses

Response samples

Content type
application/json
{
  • "msg": "Detector in wrong state",
  • "reason": "WrongDAQState"
}

Change detector configuration

Detector settings are ones that have effect on calibration, i.e., pedestal has to be collected again after changing these settings. -This can only be done when detector is Idle, Error or Inactive states. -If detector is in Idle state , pedestal procedure will be executed automatically - there must be no X-rays on the detector during the operation. -If detector is in Inactive or Error states, new settings will be saved, but no calibration will be executed.

-
Request Body schema: application/json
frame_time_us
required
integer <int64> >= 1

Interval between consecutive frames. -This is internal frame time for the JUNGFRAU detector, image time has to be integer multiply of this number. -For EIGER detector this is default frame time, not used otherwise

-
count_time_us
integer <int64>

Integration time of the detector. -If not provided count time will be set to maximum value for a given frame time.

-
internal_frame_generator
boolean
Default: false

Use internal frame generator in FPGA instead of getting data from a real detector

-
internal_frame_generator_images
integer <int64> [ 1 .. 64 ]
Default: 1

Number of images stored in the internal frame generator.

-
detector_trigger_delay_ns
integer <int64> >= 0
Default: 0

Delay between TTL trigger and acquisition start [ns]

-
timing
string (detector_timing)
Default: "trigger"
Enum: "auto" "trigger" "burst" "gated"
eiger_threshold_keV
number <float> [ 1 .. 100 ]

Threshold for the PSI EIGER detector and all DECTRIS detectors. -If value is provided, it will be used for all subsequent acquisitions, irrespective of beam energy. -If value is not provided, threshold will be determined on start of acquisition as half of incident energy. -This might lead to increased start time.

-
eiger_bit_depth
integer <int64>
Enum: 8 16 32

Bit depth of PSI EIGER read-out. This is
If value is not provided, depth will be determined based on the image time:

-
    -
  • Exposure time < 500 microseconds depth of 8 bit will be used,
  • -
  • 500 <= exposure time < 2622 microseconds depth of 16 bit will be used
  • -
  • Exposure time >= 2622 microseconds depth of 32 bit will be used.
  • -
-
jungfrau_pedestal_g0_frames
integer <int64> >= 0
Default: 2000
jungfrau_pedestal_g1_frames
integer <int64> >= 0
Default: 300
jungfrau_pedestal_g2_frames
integer <int64> >= 0
Default: 300
jungfrau_pedestal_min_image_count
integer <int64> >= 32
Default: 128

Minimum number of collected images for pedestal to consider it viable

-
jungfrau_storage_cell_count
integer <int64> [ 1 .. 16 ]
Default: 1
jungfrau_storage_cell_delay_ns
integer <int64> >= 2100
Default: 5000

Delay between two storage cells [ns]

-
jungfrau_fixed_gain_g1
boolean
Default: false

Fix gain to G1 (can be useful for storage cells)

-
jungfrau_use_gain_hg0
boolean
Default: false

Use high G0 (for low energy applications)

-

Responses

Request samples

Content type
application/json
{
  • "frame_time_us": 1,
  • "count_time_us": 0,
  • "internal_frame_generator": false,
  • "internal_frame_generator_images": 1,
  • "detector_trigger_delay_ns": 0,
  • "timing": "auto",
  • "eiger_threshold_keV": 1,
  • "eiger_bit_depth": 8,
  • "jungfrau_pedestal_g0_frames": 2000,
  • "jungfrau_pedestal_g1_frames": 300,
  • "jungfrau_pedestal_g2_frames": 300,
  • "jungfrau_pedestal_min_image_count": 128,
  • "jungfrau_storage_cell_count": 1,
  • "jungfrau_storage_cell_delay_ns": 5000,
  • "jungfrau_fixed_gain_g1": false,
  • "jungfrau_use_gain_hg0": false
}

Response samples

Content type
application/json
{
  • "msg": "Detector in wrong state",
  • "reason": "WrongDAQState"
}

Get detector configuration

Can be done anytime

-

Responses

Response samples

Content type
application/json
{
  • "frame_time_us": 1,
  • "count_time_us": 0,
  • "internal_frame_generator": false,
  • "internal_frame_generator_images": 1,
  • "detector_trigger_delay_ns": 0,
  • "timing": "auto",
  • "eiger_threshold_keV": 1,
  • "eiger_bit_depth": 8,
  • "jungfrau_pedestal_g0_frames": 2000,
  • "jungfrau_pedestal_g1_frames": 300,
  • "jungfrau_pedestal_g2_frames": 300,
  • "jungfrau_pedestal_min_image_count": 128,
  • "jungfrau_storage_cell_count": 1,
  • "jungfrau_storage_cell_delay_ns": 5000,
  • "jungfrau_fixed_gain_g1": false,
  • "jungfrau_use_gain_hg0": false
}

Change indexing algorithm settings

This can only be done when detector is Idle, Error or Inactive states.

-
Request Body schema: application/json
algorithm
required
string (indexing_algorithm)
Default: "FFBIDX"
Enum: "FFBIDX" "FFT" "FFTW" "Auto" "None"

Selection of an indexing algorithm used by Jungfraujoch

-
fft_max_unit_cell_A
required
number <float> [ 50 .. 500 ]
Default: 250

Largest unit cell to be indexed by FFT algorithm; parameter value affects execution time of FFT

-
fft_min_unit_cell_A
required
number <float> [ 5 .. 40 ]
Default: 10

Smallest unit cell to be indexed by FFT algorithm; parameter value affects execution time of FFT

-
fft_high_resolution_A
required
number <float> [ 0.5 .. 6 ]
Default: 2

Sets how finely the FFT samples each search direction: it fixes the extent of the projection -histogram, and with it the transform size, so it affects execution time and memory of FFT. -It does NOT filter spots - every spot is projected whatever its resolution, so raising it -does not make the transform see a coarser subset of the data. -There is also correlation between smallest unit cell and this value, which need to be checked for very small systems.

-
fft_num_vectors
required
integer <int64> >= 128
Default: 16384

Number of search directions for the FFT algorithm; parameter value affects execution time of FFT.

-
tolerance
required
number <float> [ 0 .. 0.5 ]

Acceptance tolerance for spots after the indexing run - the larger the number, the more spots will be accepted

-
thread_count
required
integer <int64> [ 1 .. 64 ]

Thread count for indexing algorithm

-
geom_refinement_algorithm
required
string (geom_refinement_algorithm)
Enum: "BeamCenter" "OrientationOnly" "Flex" "None"

Selection of an post-indexing least-square diffraction geometry refinement algorithm used by Jungfraujoch. -BeamCenter - This option is refining both beam center and lattice (restricted to a chosen/detected Bravais lattice). -OrientationOnly - This option is refining only orientation of the lattice. -Flex - Tries all per-image refinements and keeps whichever indexes the most spots, letting the pipeline decide (the rugnux flex mode).

-
unit_cell_dist_tolerance
required
number <float> [ 0.0001 .. 0.2001 ]
Default: 0.05

Relative distance tolerance for unit cell vs. reference; Lattices outside given tolerance will be ignored

-
viable_cell_min_spots
required
integer <int64> >= 5
Default: 10

Minimum number of indexed spots required for a cell to be considered viable

-
index_ice_rings
required
boolean
Default: false

Include spots marked as ice rings in the indexing run. -If dataset_settings doesn't have detect_ice_rings on, this option will have no effect on processing.

-
rotation_indexing
boolean
Deprecated
Default: false

Ignored: accepted on input and always returned as false; will be removed in a future release. -The Lite and FPGA workflows index each image on its own, rotation or not; rotation indexing is done by rugnux live.

-
rotation_indexing_min_angular_range_deg
number <float> >= 1
Deprecated
Default: 20

Ignored, as rotation_indexing; always returned as 20.0.

-
rotation_indexing_angular_stride_deg
number <float> >= 0
Deprecated
Default: 0.5

Ignored, as rotation_indexing; always returned as 0.5.

-
blocking
required
boolean
Default: true

Indexing in Jungfraujoch goes with a dedicated thread pool. -If set to false, the thread pool is non-blocking, i.e. if there are no threads available, image indexing will be skipped. This option is recommended for real-time processing at high frame rates. -If set to true, the thread pool will block until a thread is available.

-

Responses

Request samples

Content type
application/json
{
  • "algorithm": "FFBIDX",
  • "fft_max_unit_cell_A": 250,
  • "fft_min_unit_cell_A": 10,
  • "fft_high_resolution_A": 2,
  • "fft_num_vectors": 16384,
  • "tolerance": 0.5,
  • "thread_count": 1,
  • "geom_refinement_algorithm": "BeamCenter",
  • "unit_cell_dist_tolerance": 0.05,
  • "viable_cell_min_spots": 10,
  • "index_ice_rings": false,
  • "rotation_indexing": false,
  • "rotation_indexing_min_angular_range_deg": 20,
  • "rotation_indexing_angular_stride_deg": 0.5,
  • "blocking": true
}

Response samples

Content type
application/json
{
  • "msg": "Detector in wrong state",
  • "reason": "WrongDAQState"
}

Get indexing configuration

Can be done anytime

-

Responses

Response samples

Content type
application/json
{
  • "algorithm": "FFBIDX",
  • "fft_max_unit_cell_A": 250,
  • "fft_min_unit_cell_A": 10,
  • "fft_high_resolution_A": 2,
  • "fft_num_vectors": 16384,
  • "tolerance": 0.5,
  • "thread_count": 1,
  • "geom_refinement_algorithm": "BeamCenter",
  • "unit_cell_dist_tolerance": 0.05,
  • "viable_cell_min_spots": 10,
  • "index_ice_rings": false,
  • "rotation_indexing": false,
  • "rotation_indexing_min_angular_range_deg": 20,
  • "rotation_indexing_angular_stride_deg": 0.5,
  • "blocking": true
}

Change Bragg integration settings

This can only be done when detector is Idle, Error or Inactive states.

-
Request Body schema: application/json
integration_model
required
string (integration_model)
Default: "ProfileGaussian"
Enum: "ProfileGaussian" "ProfileEmpirical" "BoxSum"

Bragg spot integration model. -ProfileGaussian - profile fit with a measured-width Gaussian (Kabsch-style), the default; more - accurate intensities than box summation. -ProfileEmpirical - profile fit with a per-resolution-shell empirical profile learned from strong spots. -BoxSum - classical uniform box summation minus a ring-mean background; the simpler, faster fallback.

-
max_hkl
integer [ 1 .. 511 ]
Default: 100

How far the Bragg predictor walks the lattice: reflections with |h|,|k|,|l| above this are -never predicted. An axis is truncated once a/d_min exceeds it, so a long axis - or a short -one taken to high resolution - loses its outermost reflections. The cost grows as the cube -(2n+1)^3 of candidates per image, which is why online keeps a fixed, predictable value -instead of taking it from whichever crystal is mounted.

-

Omitting the field selects the default above; it is never interpreted as "choose per -crystal". The offline tools (rugnux, viewer) do derive it from the refined cell when it is -left unset there, but that is their own default and is not reachable through this API.

-

Responses

Request samples

Content type
application/json
{
  • "integration_model": "ProfileGaussian",
  • "max_hkl": 100
}

Response samples

Content type
application/json
{
  • "msg": "Detector in wrong state",
  • "reason": "WrongDAQState"
}

Get Bragg integration configuration

Can be done anytime

-

Responses

Response samples

Content type
application/json
{
  • "integration_model": "ProfileGaussian",
  • "max_hkl": 100
}

Change file writer settings

This can only be done when detector is Idle, Error or Inactive states.

-
Request Body schema: application/json
overwrite
boolean
Default: false

Inform jfjoch_write to overwrite existing files. Otherwise files would be saved with .h5.{timestamp}.tmp suffix.

-
format
string (file_writer_format)
Default: "NXmxVDS"
Enum: "NXmxOnlyData" "NXmxLegacy" "NXmxVDS" "NXmxIntegrated" "CBF" "TIFF" "NoFileWritten"

NoFileWritten - no files are written at all -NXmxOnlyData - only data files are written, no master file -NXmxLegacy - legacy format with soft links to data files in the master file; necessary for DECTRIS Albula 4.0 and DECTRIS Neggia -NXmxVDS - newer format with virtual dataset linking data files in the master file, also includes better metadata handling -NXmxIntegrated - single HDF5 per dataset -CBF - DEPRECATED, no longer supported; kept for back compatibility only. Requests using this value are rejected. Only HDF5 formats are written. -TIFF - DEPRECATED, no longer supported; kept for back compatibility only. Requests using this value are rejected. Only HDF5 formats are written.

-

Responses

Request samples

Content type
application/json
{
  • "overwrite": false,
  • "format": "NXmxOnlyData"
}

Response samples

Content type
application/json
{
  • "msg": "Detector in wrong state",
  • "reason": "WrongDAQState"
}

Get file writer settings

Can be done anytime

-

Responses

Response samples

Content type
application/json
{
  • "overwrite": false,
  • "format": "NXmxOnlyData"
}

Change instrument metadata

This can only be done when detector is Idle, Error or Inactive states.

-
Request Body schema: application/json
source_name
required
string
source_type
string
Default: ""

Type of radiation source. NXmx gives a fixed dictionary, though Jungfraujoch is not enforcing compliance. -https://manual.nexusformat.org/classes/base_classes/NXsource.html#nxsource -NXsource allows the following:

-

Spallation Neutron Source -Pulsed Reactor Neutron Source -Reactor Neutron Source -Synchrotron X-ray Source -Pulsed Muon Source -Rotating Anode X-ray -Fixed Tube X-ray -UV Laser -Free-Electron Laser -Optical Laser -Ion Source -UV Plasma Source -Metal Jet X-ray

-
instrument_name
required
string
pulsed_source
boolean
Default: false

Settings specific to XFEL (e.g., every image has to come from TTL trigger, save pulse ID and event code)

-
electron_source
boolean
Default: false

Settings specific to electron source (e.g., wavelength definition)

-

Responses

Request samples

Content type
application/json
{
  • "source_name": "Swiss Light Source",
  • "source_type": "Synchrotron X-ray Source",
  • "instrument_name": "CristallinaMX",
  • "pulsed_source": false,
  • "electron_source": false
}

Response samples

Content type
application/json
{
  • "msg": "Detector in wrong state",
  • "reason": "WrongDAQState"
}

Get instrument metadata

Can be done anytime

-

Responses

Response samples

Content type
application/json
{
  • "source_name": "Swiss Light Source",
  • "source_type": "Synchrotron X-ray Source",
  • "instrument_name": "CristallinaMX",
  • "pulsed_source": false,
  • "electron_source": false
}

Change image output format

This can only be done when detector is Idle, Error or Inactive states.

-
Request Body schema: application/json
summation
required
boolean

Enable summation of images to a given image_time -If disabled images are saved according to original detector speed, but image count is adjusted

-
geometry_transform
required
boolean

Place module read-out into their location on composed detector and extend multipixels

-
jungfrau_conversion
required
boolean

Convert pixel value in ADU to photon counts/energy -Only affects JUNGFRAU detector

-
jungfrau_conversion_factor_keV
number <float> [ 0.001 .. 500 ]

Used to convert energy deposited into pixel to counts -If not provided incident_energy_keV is used

-
bit_depth_image
integer <int64>
Enum: 8 16 32

Bit depth of resulting image (it doesn't affect the detector read-out value) -If not provided value is adjusted automatically

-
signed_output
boolean

Controls if pixels have signed output -If not provided value is adjusted automatically

-
mask_module_edges
required
boolean
Default: true

Mask 1 pixel on the module boundary

-
mask_chip_edges
required
boolean
Default: true

Mask multipixels on chip boundary

-
jungfrau_mask_pixels_without_g0
boolean
Default: true

JUNGFRAU: mask pixels that don't operate in G0, but do operate in G1 and G1. -This should be turned off for cases, where detector is operated at room temperature with long exposure time.

-
apply_mask
required
boolean
Default: false

Masked pixels are set to special value in the images produced by Jungfraujoch

-
jungfrau_pedestal_g0_rms_limit
integer <int64> >= 0
Default: 100

Pixels with pedestal G0 RMS above the threshold are marked as masked pixels

-

Responses

Request samples

Content type
application/json
{
  • "summation": true,
  • "geometry_transform": true,
  • "jungfrau_conversion": true,
  • "jungfrau_conversion_factor_keV": 0.001,
  • "bit_depth_image": 8,
  • "signed_output": true,
  • "mask_module_edges": true,
  • "mask_chip_edges": true,
  • "jungfrau_mask_pixels_without_g0": true,
  • "apply_mask": false,
  • "jungfrau_pedestal_g0_rms_limit": 100
}

Response samples

Content type
application/json
{
  • "msg": "Detector in wrong state",
  • "reason": "WrongDAQState"
}

Get image output format

Can be done anytime

-

Responses

Response samples

Content type
application/json
{
  • "summation": true,
  • "geometry_transform": true,
  • "jungfrau_conversion": true,
  • "jungfrau_conversion_factor_keV": 0.001,
  • "bit_depth_image": 8,
  • "signed_output": true,
  • "mask_module_edges": true,
  • "mask_chip_edges": true,
  • "jungfrau_mask_pixels_without_g0": true,
  • "apply_mask": false,
  • "jungfrau_pedestal_g0_rms_limit": 100
}

Configure format for raw data collection

This can only be done when detector is Idle, Error or Inactive states.

-

Responses

Response samples

Content type
application/json
{
  • "msg": "Detector in wrong state",
  • "reason": "WrongDAQState"
}

Configure format for data collection with full conversion

This can only be done when detector is Idle, Error or Inactive states.

-

Responses

Response samples

Content type
application/json
{
  • "msg": "Detector in wrong state",
  • "reason": "WrongDAQState"
}

Configure spot finding

Can be done anytime, also while data collection is running

-
Request Body schema: application/json
enable
required
boolean
Default: true

Enable spot finding. This is temporary setting, i.e. can be changed anytime during data collection. -Even if disabled spot finding information will still be send and written, though always with zero spots.

-
indexing
required
boolean
Default: true

Enable indexing. This is temporary setting, i.e. can be changed anytime during data collection.

-
signal_to_noise_threshold
required
number <float> >= 0
photon_count_threshold
required
integer <int64> >= 0
min_pix_per_spot
required
integer <int64> >= 1
max_pix_per_spot
required
integer <int64> >= 1
high_resolution_limit
number <float>

High resolution limit for spot finding [Angstrom]. Optional: if omitted, spot finding extends -as far as the detector reaches, i.e. the detection is not clipped in resolution.

-
low_resolution_limit
number <float>

Low resolution limit for spot finding [Angstrom]. Optional: if omitted, spot finding is not -clipped at the low-resolution end. A value of 0 is accepted and means the same thing.

-
high_resolution_limit_for_spot_count_low_res
required
number <float> [ 2 .. 8 ]

High resolution threshold to consider spot "low resolution" [Angstrom]

-
quick_integration
boolean
Deprecated
Default: false

Ignored: accepted on input and always returned as false; will be removed in a future release. -The Lite and FPGA workflows index images but do not integrate them; integration is done by rugnux live.

-
ice_ring_width_q_recipA
required
number <float> [ 0 .. 1 ]
Default: 0.03

Half-width of the ice ring band in q (1/A). Matches the offline default in image_analysis/spot_finding/SpotFindingSettings.h, which was set from a measured ring FWHM of ~0.06; the two must agree or the same data gets a narrower ice band online.

-
high_res_gap_Q_recipA
number <float> [ 0.1 .. 5 ]
Default: 1.5

This parameter is used to remove spurious spots at a very high resolution, that sometimes appear due to very low background close to the edge of the detector. -If there is a gap in (1/d)-space between spots of at least this size, spots on the side of the gap with high resolution will be discarded. This is optional parameter. -This option should be turned OFF for small molecule datasets or for crystals with very low mosaicity, when it is expected to see only few spots in any case.

-
adaptive_threshold
boolean
Default: false

Self-calibrating spot detection: replace the fixed photon_count_threshold by a per-resolution-ring -threshold derived from each image's own noise, so the same setting works across datasets without -per-dataset tuning. photon_count_threshold is then ignored and false_pixels_per_frame sets the -operating point instead. -Used only on detectors whose images are analysed in software (the DECTRIS/SIMPLON workflow). -The JUNGFRAU and EIGER workflows find spots on the FPGA, which applies its own fixed threshold; -there the setting is accepted and ignored, so the same settings can be shared across detectors.

-
false_pixels_per_frame
number <float> [ 1 .. 100000 ]
Default: 100

Operating point of the adaptive threshold: the number of noise pixels tolerated per frame. -About 100 suits a multi-megapixel detector. Ignored unless adaptive_threshold is set.

-

Responses

Request samples

Content type
application/json
{
  • "enable": true,
  • "indexing": true,
  • "signal_to_noise_threshold": 0.1,
  • "photon_count_threshold": 0,
  • "min_pix_per_spot": 1,
  • "max_pix_per_spot": 1,
  • "high_resolution_limit": 0.1,
  • "low_resolution_limit": 0.1,
  • "high_resolution_limit_for_spot_count_low_res": 2,
  • "quick_integration": false,
  • "ice_ring_width_q_recipA": 0.03,
  • "high_res_gap_Q_recipA": 1.5,
  • "adaptive_threshold": false,
  • "false_pixels_per_frame": 100
}

Get data processing configuration

Can be done anytime

-

Responses

Response samples

Content type
application/json
{
  • "enable": true,
  • "indexing": true,
  • "signal_to_noise_threshold": 0.1,
  • "photon_count_threshold": 0,
  • "min_pix_per_spot": 1,
  • "max_pix_per_spot": 1,
  • "high_resolution_limit": 0.1,
  • "low_resolution_limit": 0.1,
  • "high_resolution_limit_for_spot_count_low_res": 2,
  • "quick_integration": false,
  • "ice_ring_width_q_recipA": 0.03,
  • "high_res_gap_Q_recipA": 1.5,
  • "adaptive_threshold": false,
  • "false_pixels_per_frame": 100
}

Configure azimuthal integration

Can be done when detector is Inactive or Idle

-
Request Body schema: application/json
polarization_corr
required
boolean
Default: true

Apply polarization correction for azimuthal integration (polarization factor must be configured in dataset settings)

-
solid_angle_corr
required
boolean
Default: true

Apply solid angle correction for azimuthal integration

-
high_q_recipA
number <float> [ 0.00002 .. 10 ]

Upper q limit of the azimuthal integration [1/Angstrom]. Optional: if omitted, the integration -(and the adaptive spot detection that shares these q bins) extends to the highest q the -detector reaches.

-
low_q_recipA
required
number <float> [ 0.00001 .. 10 ]
q_spacing
number <float> >= 0.00001

Width of a Q bin [1/Angstrom], for linear binning only. Linear binning takes either this or -q_bins, not both; with neither, the spacing is 0.01 1/Angstrom.

-
q_bins
integer <int64> [ 1 .. 65534 ]

Number of Q bins between low and high Q. Required for log10 binning; for linear binning -an alternative to q_spacing.

-
q_binning
string (q_binning)
Default: "linear"
Enum: "linear" "log10"

How the Q bins of azimuthal integration are laid out between low and high Q. -linear - equal steps in Q. -log10 - equal steps in log10(Q): fine bins at low Q, coarse at high Q. Needs q_bins.

-
azimuthal_bins
integer <int64> [ 1 .. 512 ]
Default: 1

Numer of azimuthal (phi) bins; 1 = standard 1D azimuthal integration

-
force_cpu
boolean
Default: false

Force CPU processing of azimuthal integration in the FPGA data acquisition workflow. -This allows to extend number of azimuthal integration bins, as well as to calculate standard deviation -of the azimuthal integration results.

-

Responses

Request samples

Content type
application/json
{
  • "polarization_corr": true,
  • "solid_angle_corr": true,
  • "high_q_recipA": 0.00002,
  • "low_q_recipA": 0.00001,
  • "q_spacing": 0.00001,
  • "q_bins": 1,
  • "q_binning": "linear",
  • "azimuthal_bins": 1,
  • "force_cpu": false
}

Response samples

Content type
application/json
{
  • "msg": "Detector in wrong state",
  • "reason": "WrongDAQState"
}

Get azimuthal integration configuration

Can be done anytime

-

Responses

Response samples

Content type
application/json
{
  • "polarization_corr": true,
  • "solid_angle_corr": true,
  • "high_q_recipA": 0.00002,
  • "low_q_recipA": 0.00001,
  • "q_spacing": 0.00001,
  • "q_bins": 1,
  • "q_binning": "linear",
  • "azimuthal_bins": 1,
  • "force_cpu": false
}

Load binary image for internal FPGA generator

Load image for internal FPGA generator. This can only happen in Idle state of the detector. -Requires binary blob with 16-bit integer numbers of size of detector in raw/converted coordinates -(depending on detector settings).

-
query Parameters
id
integer <int64> [ 0 .. 127 ]

Image id to upload

-
Request Body schema: application/octet-stream
string <binary>

Responses

Load TIFF image for internal FPGA generator

Load image for internal FPGA generator. This can only happen in Idle state of the detector. -Requires TIFF with 16-bit integer numbers of size of detector in raw/converted coordinates -(depending on detector settings).

-
query Parameters
id
integer [ 0 .. 127 ]

Image ID to upload

-
Request Body schema: image/tiff
string <binary>

Responses

Select detector

Jungfraujoch allows to control multiple detectors and/or region-of-interests. -The command allows to choose one detector from the list (ID has to be consistent with one provided by GET response). -Changing detector will set detector to Inactive state and will require reinitialization.

-
Request Body schema: application/json
id
required
integer <int64>

Responses

Request samples

Content type
application/json
{
  • "id": 1
}

Response samples

Content type
application/json
{
  • "msg": "Detector in wrong state",
  • "reason": "WrongDAQState"
}

List available detectors

Configured detectors that can be selected by used

-

Responses

Response samples

Content type
application/json
{
  • "detectors": [
    ],
  • "current_id": 0
}

Change rugnux live mode settings

This can only be done when detector is Idle, Error or Inactive states.

-
Request Body schema: application/json
enable
boolean
Default: false

Process DECTRIS rotation collections with rugnux live, and serial collections on the GPU after a pre-pass

-
reserved_cpus
integer <int64> >= 0
Default: 4

CPU threads left to the receiver and the image pusher while rugnux runs

-
deadline_s
number <double> >= 0
Default: 60

Fixed cutoff: this long after the last image the analysis is cut, and the collection ends -with what it has established (as POST /cancel after the last image does). 0 means no cutoff.

-
refine_solvent
boolean
Default: false

With a model: the refinement also builds the solvent - waters added at difference-map peaks and removed -where the maps no longer hold them, waters and ions relabelled (as rugnux --refine-solvent). -Reset to false by POST /initialize.

-
force_still
boolean
Default: false

Process DECTRIS rotation collections as stills, on the serial path (pre-pass, GPU analysis, stills merge), -as rugnux --force-still does. The written file keeps its goniometer. Reset to false by POST /initialize.

-

Responses

Request samples

Content type
application/json
{
  • "enable": false,
  • "reserved_cpus": 4,
  • "deadline_s": 60,
  • "refine_solvent": false,
  • "force_still": false
}

Response samples

Content type
application/json
{
  • "msg": "Detector in wrong state",
  • "reason": "WrongDAQState"
}

Get rugnux live mode settings and model status

Can be done anytime

-

Responses

Response samples

Content type
application/json
{
  • "enable": true,
  • "reserved_cpus": 0,
  • "deadline_s": 0.1,
  • "refine_solvent": true,
  • "force_still": true,
  • "model_loaded": true,
  • "model_size_bytes": 0
}

Upload the model used by rugnux live mode

This can only be done when detector is Idle, Error or Inactive states. -The model (PDB or mmCIF, optionally gzipped; at most 64 MiB) is used for molecular replacement -and validation of every following rugnux live collection, until it is removed with -DELETE /config/rugnux/model or replaced by another upload.

-
Request Body schema: application/octet-stream
string <binary>

Responses

Response samples

Content type
application/json
{
  • "msg": "Detector in wrong state",
  • "reason": "WrongDAQState"
}

Remove the model used by rugnux live mode

This can only be done when detector is Idle, Error or Inactive states.

-

Responses

Response samples

Content type
application/json
{
  • "msg": "Detector in wrong state",
  • "reason": "WrongDAQState"
}

Get live rugnux processing status of the last collection

Can be done anytime

-
Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "state": "Idle",
  • "placed_model": true,
  • "refined_model": true,
  • "anomalous_map": true,
  • "anomalous_signal": true,
  • "model": {
    },
  • "stills": {
    },
  • "shells_merge": "string",
  • "shells": [
    ],
  • "overall": {
    },
  • "frame_scales": [
    ],
  • "frame_ranges": [
    ],
  • "space_group": "string",
  • "d_min": 0.1,
  • "resolution_fit": 0.1,
  • "isa": 0.1,
  • "probe": "string",
  • "probe_s": 0.1,
  • "start_to_first_image_s": 0.1,
  • "message": "string",
  • "images_expected": 0,
  • "expected_collection_s": 0.1,
  • "images_received": 0,
  • "elapsed_s": 0.1,
  • "step_progress": 1,
  • "steps": [
    ],
  • "last_image_s": 0.1,
  • "cut": "string",
  • "cut_s": 0.1,
  • "last_image_to_written_s": 0.1,
  • "verdict": "string",
  • "verdict_text": "string",
  • "summary": [
    ],
  • "warnings": [
    ],
  • "triage": [
    ]
}

Clear the live rugnux result of the last collection

Puts /rugnux/status back to Idle with nothing of the last run - its merge, model, maps, steps and notes - -as before any collection. The collection's images, plots and the rugnux live settings are kept. -Can be only run when Jungfraujoch is not collecting data.

-

Responses

Response samples

Content type
application/json
{
  • "msg": "Detector in wrong state",
  • "reason": "WrongDAQState"
}

Get the model as placed by the last rugnux live run

The model placed against the data by molecular replacement or validation, as mmCIF - the same text as the -_model.cif file written beside the data: the data's cell and space group, with the input model's own -metadata (entities, sequences, references, authors, software) kept. Kept as long as /rugnux/status. -Where the run refined the model, the refined model unless asked for stage=placed.

-
Authorizations:
bearerAuth
query Parameters
stage
string
Enum: "placed" "refined"

placed: the model as placed; refined: the model refined (refined_model in /rugnux/status). -Default: the refined model where there is one, otherwise the placed one.

-

Responses

Get an electron-density map of the last rugnux live run

The map of the placed model (/rugnux/model.cif) in CCP4 format (mode 2, float), made from the map -coefficients written to _maps.mtz (FWT/PHWT, DELFWT/PHDELWT, ANOM/PHANOM). It covers one unit cell centred on the model - along an axis where -the model reaches further than the cell, the model plus 5 A instead - sampled every d_min/3; the mean and -RMS in its header are those of the unit cell, so contour levels in sigma are the usual ones. Where the run -refined the model, the 2mFo-DFc and mFo-DFc maps are the refined model's unless asked for stage=placed; -the anomalous map stays on the placed model's phases.

-
Authorizations:
bearerAuth
query Parameters
type
string
Default: "2fofc"
Enum: "2fofc" "fofc" "anom"

2fofc: the 2mFo-DFc map; fofc: the mFo-DFc difference map; anom: the anomalous difference map, -(F(+) - F(-)) on the model phases less 90 degrees, where the merge kept the Bijvoet pairs (anomalous_map -in /rugnux/status)

-
stage
string
Enum: "placed" "refined"

placed: the model as placed; refined: the model refined (refined_model in /rugnux/status). -Default: the refined model where there is one, otherwise the placed one.

-

Responses

Set ZeroMQ preview settings

Jungfraujoch can generate preview message stream on ZeroMQ SUB socket. -Here settings of the socket can be adjusted. -While the data structure contains also socket_address, this cannot be changed via HTTP and is ignore in PUT request. -Options set with this PUT request have no effect on HTTP based preview.

-
Request Body schema: application/json
enabled
required
boolean
Default: true

ZeroMQ preview socket is enabled.

-
period_ms
required
integer <int64>
Default: 1000

Period for generating preview image sent to the ZeroMQ interface in milliseconds. Default is 1 second. -If set to zero, all images will be sent ZeroMQ (should be used only in case of relatively slow data collection). -This has no effect on HTTP based preview, which updates always at rate of 1 second.

-
socket_address
string

PUB ZeroMQ socket for preview images. This socket operates at a reduced frame rate. -Images are serialized using CBOR. -Address follows ZeroMQ convention for sockets - in practice ipc:// and tcp://: sockets are OK. -0.0.0.0 instead of IP address is accepted and means listening on all network interfaces.

-

Responses

Request samples

Content type
application/json
{
  • "enabled": true,
  • "period_ms": 1000,
  • "socket_address": "string"
}

Response samples

Content type
application/json
{
  • "msg": "Detector in wrong state",
  • "reason": "WrongDAQState"
}

Get ZeroMQ preview settings

Responses

Response samples

Content type
application/json
{
  • "enabled": true,
  • "period_ms": 1000,
  • "socket_address": "string"
}

Set ZeroMQ metadata settings

Jungfraujoch can generate metadata message stream on ZeroMQ PUB socket. This stream covers all images. -Here settings of the socket can be adjusted. -While the data structure contains also socket_address, this cannot be changed via HTTP and is ignore in PUT request.

-
Request Body schema: application/json
enabled
required
boolean
Default: true

ZeroMQ metadata socket is enabled.

-
period_ms
required
integer <int64> >= 1
Default: 1000

Period for generating metadata package sent to the ZeroMQ interface in milliseconds.

-
socket_address
string

PUB ZeroMQ socket for image metadata information. -Image metadata are serialized using CBOR. -Address follows ZeroMQ convention for sockets - in practice ipc:// and tcp://: sockets are OK. -0.0.0.0 instead of IP address is accepted and means listening on all network interfaces.

-

Responses

Request samples

Content type
application/json
{
  • "enabled": true,
  • "period_ms": 1000,
  • "socket_address": "string"
}

Response samples

Content type
application/json
{
  • "msg": "Detector in wrong state",
  • "reason": "WrongDAQState"
}

Get ZeroMQ metadata socket settings

Responses

Response samples

Content type
application/json
{
  • "enabled": true,
  • "period_ms": 1000,
  • "socket_address": "string"
}

Set configuration for dark data collection to calculate mask

This is only possible when operating DECTRIS detectors at the moment; it will be also available for PSI EIGER at some point. -This can only be done when detector is Idle, Error or Inactive states.

-
Request Body schema: application/json
detector_threshold_keV
required
number <float> [ 2.5 .. 100 ]
Default: 3.5

Energy threshold for dark image collection

-
frame_time_us
required
integer <int64> [ 500 .. 100000 ]
Default: 10000

Time between frames for dark image collection

-
number_of_frames
required
integer <int64> >= 0
Default: 1000

Number of frames for dark image collection; zero means no dark collection

-
max_allowed_pixel_count
required
integer <int64> >= 0
Default: 1

Maximum count in a pixel considered normal (not-masked)

-
max_frames_with_signal
required
integer <int64> >= 0
Default: 10

Maximum number of frames with signal in a pixel considered normal (not-masked)

-

Responses

Request samples

Content type
application/json
{
  • "detector_threshold_keV": 3.5,
  • "frame_time_us": 10000,
  • "number_of_frames": 1000,
  • "max_allowed_pixel_count": 1,
  • "max_frames_with_signal": 10
}

Response samples

Content type
application/json
{
  • "msg": "Detector in wrong state",
  • "reason": "WrongDAQState"
}

Get settings for dark data collection to calculate mask

Responses

Response samples

Content type
application/json
{
  • "detector_threshold_keV": 3.5,
  • "frame_time_us": 10000,
  • "number_of_frames": 1000,
  • "max_allowed_pixel_count": 1,
  • "max_frames_with_signal": 10
}

Get Jungfraujoch status

Status of the data acquisition

-

Responses

Response samples

Content type
application/json
{
  • "state": "Inactive",
  • "progress": 1,
  • "message": "string",
  • "message_severity": "success",
  • "gpu_count": 0,
  • "broker_version": "1.0.0-rc.128"
}

Get status of FPGA devices

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Return XFEL pulse IDs for the current data acquisition

Return array of XFEL pulse IDs - (-1) if image not recorded

-

Responses

Response samples

Content type
application/json
[
  • 0
]

Return XFEL event codes for the current data acquisition

Return array of XFEL event codes

-

Responses

Response samples

Content type
application/json
[
  • 0
]

Get status of image pusher

Responses

Response samples

Content type
application/json
{
  • "pusher_type": "ZeroMQ",
  • "addr": [
    ],
  • "connected_writers": 0,
  • "images_written": 0,
  • "images_write_error": 0,
  • "writer_fifo_utilization": [
    ]
}

Get detector status

Status of the JUNGFRAU detector

-

Responses

Response samples

Content type
application/json
{
  • "state": "Idle",
  • "powerchip": "PowerOn",
  • "server_version": "string",
  • "number_of_triggers_left": 0,
  • "fpga_temp_degC": [
    ],
  • "high_voltage_V": [
    ]
}

Get ROI definitions

Responses

Response samples

Content type
application/json
{
  • "box": {
    },
  • "circle": {
    },
  • "azim": {
    }
}

Upload ROI definitions

Request Body schema: application/json
required
object (roi_box_list)

List of box ROIs

-
required
object (roi_circle_list)

List of circular ROIs

-
required
object (roi_azim_list)

List of azimuthal ROIs

-

Responses

Request samples

Content type
application/json
{
  • "box": {
    },
  • "circle": {
    },
  • "azim": {
    }
}

Response samples

Content type
application/json
{
  • "msg": "Detector in wrong state",
  • "reason": "WrongDAQState"
}

Get general statistics

measurement is omitted unless the request carries a valid bearer token for a protected -dataset (see tokens in /start).

-

Responses

Response samples

Content type
application/json
{
  • "detector": {
    },
  • "detector_list": {
    },
  • "detector_settings": {
    },
  • "image_format_settings": {
    },
  • "instrument_metadata": {
    },
  • "file_writer_settings": {
    },
  • "data_processing_settings": {
    },
  • "measurement": {
    },
  • "broker": {
    },
  • "fpga": [
    ],
  • "calibration": [
    ],
  • "zeromq_preview": {
    },
  • "zeromq_metadata": {
    },
  • "dark_mask": {
    },
  • "pixel_mask": {
    },
  • "roi": {
    },
  • "az_int": {
    },
  • "buffer": {
    },
  • "indexing": {
    },
  • "bragg_integration": {
    },
  • "image_pusher": {
    }
}

Get data collection statistics

Results of the last data collection (dataset name, unit cell, ...)

-
Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "file_prefix": "string",
  • "run_number": 0,
  • "experiment_group": "string",
  • "images_expected": 0,
  • "images_collected": 0,
  • "images_sent": 0,
  • "images_written": 0,
  • "images_discarded_lossy_compression": 0,
  • "max_image_number_sent": 0,
  • "collection_efficiency": 1,
  • "compression_ratio": 5.3,
  • "cancelled": true,
  • "max_receiver_delay": 0,
  • "indexing_rate": 0.1,
  • "detector_width": 0,
  • "detector_height": 0,
  • "detector_pixel_depth": 2,
  • "bkg_estimate": 0.1,
  • "unit_cell": "string",
  • "error_pixels": 0.1,
  • "saturated_pixels": 0.1,
  • "roi_beam_pixels": 0.1,
  • "roi_beam_sum": 0.1
}

Get calibration statistics

Statistics are provided for each module/storage cell separately

-

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get mask of the detector (binary)

Detector must be Initialized. -Get full pixel mask of the detector. -See NXmx standard for meaning of pixel values.

-

Responses

Detector must be Initialized. -Get user mask of the detector (binary) -

Get user pixel mask of the detector in the actual detector coordinates: 0 - good pixel, 1 - masked

-

Responses

Upload user mask of the detector (binary)

Should be in Idle state. -Upload user mask of the detector - this is for example to account for beam stop shadow or misbehaving regions. -If detector is conversion mode the mask can be both in raw (1024x512; stacked modules) or converted coordinates. -In the latter case - module gaps are ignored and don't need to be assigned value. -Mask is expected as binary array (4-byte; unsigned). -0 - good pixel, other value - masked -User mask is stored in NXmx pixel mask (bit 8), as well as used in spot finding and azimuthal integration.

-
Request Body schema: application/octet-stream
string <binary>

Responses

Response samples

Content type
application/json
{
  • "msg": "Detector in wrong state",
  • "reason": "WrongDAQState"
}

Get mask of the detector (TIFF)

Should be in Idle state. -Get full pixel mask of the detector -See NXmx standard for meaning of pixel values

-

Responses

Detector must be Initialized. -Get user mask of the detector (TIFF) -

Get user pixel mask of the detector in the actual detector coordinates: 0 - good pixel, 1 - masked

-

Responses

Upload user mask of the detector

Should be in Idle state. -Upload user mask of the detector - this is for example to account for beam stop shadow or misbehaving regions. -If detector is conversion mode the mask can be both in raw (1024x512; stacked modules) or converted coordinates. -In the latter case - module gaps are ignored and don't need to be assigned value. -Mask is expected as a single-channel TIFF (8-, 16- or 32-bit integer, signed or unsigned). -0 - good pixel, other value - masked -User mask is stored in NXmx pixel mask (bit 8), as well as used in spot finding and azimuthal integration. -User mask is not automatically applied - i.e. pixels with user mask will have a valid pixel value in the images.

-
Request Body schema: image/tiff
string <binary>

Responses

Response samples

Content type
application/json
{
  • "msg": "Detector in wrong state",
  • "reason": "WrongDAQState"
}

Get pedestal in TIFF format

query Parameters
gain_level
required
integer

Gain level (0, 1, 2)

-
sc
integer

Storage cell number

-

Responses

Generate 1D plot from Jungfraujoch

Authorizations:
bearerAuth
query Parameters
binning
integer
Default: 1

Binning of frames for the plot (0 = default binning)

-
type
required
string
Enum: "bkg_estimate" "spindle_blind_fraction" "azint" "azint_1d" "spot_count" "spot_count_low_res" "spot_count_indexed" "spot_count_ice" "indexing_rate" "indexing_lattice_count" "indexing_unit_cell_length" "indexing_unit_cell_angle" "profile_radius" "mosaicity" "b_factor" "error_pixels" "saturated_pixels" "image_collection_efficiency" "receiver_delay" "receiver_free_send_buf" "strong_pixels" "roi_sum" "roi_mean" "roi_max_count" "roi_pixels" "roi_weighted_x" "roi_weighted_y" "packets_received" "max_pixel_value" "resolution_estimate" "pixel_sum" "processing_time" "beam_center_x" "beam_center_y" "integrated_reflections" "image_scale_factor" "image_scale_cc" "compression_ratio" "ice_ring_score"

Type of requested plot

-
fill
number <float>

Fill value for elements that were missed during data collection

-
experimental_coord
boolean
Default: false

If measurement has goniometer axis defined, plot X-axis will represent rotation angle -If measurement has grid scan defined, plot X-axis and Y-axis will represent grid position, Z will be used as the final value -For still measurement the number is ignored

-
azint_unit
string
Default: "Q_recipA"
Enum: "Q_recipA" "d_A" "two_theta_deg"

Unit used for azim int.

-

Responses

Response samples

Content type
application/json
{
  • "title": "string",
  • "unit_x": "image_number",
  • "size_x": 0.1,
  • "size_y": 0.1,
  • "plot": [
    ]
}

Generate 1D plot from Jungfraujoch and send in raw binary format. -Data are provided as (32-bit) float binary array. -This format doesn't transmit information about X-axis, only values, so it is of limited use for azimuthal integration. -

Authorizations:
bearerAuth
query Parameters
type
required
string
Enum: "bkg_estimate" "spindle_blind_fraction" "azint" "azint_1d" "spot_count" "spot_count_low_res" "spot_count_indexed" "spot_count_ice" "indexing_rate" "indexing_lattice_count" "indexing_unit_cell_length" "indexing_unit_cell_angle" "profile_radius" "mosaicity" "b_factor" "error_pixels" "saturated_pixels" "image_collection_efficiency" "receiver_delay" "receiver_free_send_buf" "strong_pixels" "roi_sum" "roi_mean" "roi_max_count" "roi_pixels" "roi_weighted_x" "roi_weighted_y" "packets_received" "max_pixel_value" "resolution_estimate" "pixel_sum" "processing_time" "beam_center_x" "beam_center_y" "integrated_reflections" "image_scale_factor" "image_scale_cc" "compression_ratio" "ice_ring_score"

Type of requested plot

-
roi
string non-empty

Name of ROI for which plot is requested

-

Responses

Get full scan result

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "file_prefix": "string",
  • "rotation_unit_cell": {
    },
  • "rotation_crystal_lattice": [
    ],
  • "rotation_bravais": "string",
  • "images": [
    ]
}

Get Start message in CBOR format

Contains metadata for a dataset (e.g., experimental geometry)

-
Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "msg": "Detector in wrong state",
  • "reason": "WrongDAQState"
}

Event stream of the collection, for a reader following it

Server-sent events (text/event-stream) for the current collection, from the moment /start has -accepted it: first its whole history, then every change, until it ends or a new collection -begins. Only one reader at a time. Events, each with a JSON data line:

-
    -
  • start {run_number, run_name, file_prefix, number_of_images, images_per_file, cbor} - first, -once the start message is known: at once for a JUNGFRAU, when the detector sends its own for -a DECTRIS. cbor is the start message the writer of the master file received, CBOR in base64; -a reader builds the dataset from it;
  • -
  • file {file_number, file, first_image, image_count} - a data file closed and renamed into -place; file is relative to the collection's root, as the writer named it;
  • -
  • end {images, error?} - every writer acknowledged the end: the data files and the master -file are in place; images is the number of images collected. Also sent, with error, when -the measurement ends any other way - before the start message, for one. The stream then closes;
  • -
  • superseded {run_number} - a new collection began. The stream then closes. -A comment line (: keepalive) every 10 s when nothing happens.
  • -
-
Authorizations:
bearerAuth

Responses

Get image message in CBOR format

Contains full image data and metadata. The image must come from the latest data collection.

-
Authorizations:
bearerAuth
query Parameters
id
integer <int64> >= -2
Default: -1

Image ID in the image buffer. Special values: -1 - last image in the buffer, -2: last indexed image in the buffer

-

Responses

Response samples

Content type
application/json
{
  • "msg": "Detector in wrong state",
  • "reason": "WrongDAQState"
}

Get preview image in JPEG format using custom settings

Authorizations:
bearerAuth
query Parameters
id
integer <int64> >= -2
Default: -1

Image ID in the image buffer. Special values: -1 - last image in the buffer, -2: last indexed image in the buffer

-
show_user_mask
boolean
Default: false

Show user mask

-
show_roi
boolean
Default: false

Show ROI areas on the image

-
show_spots
boolean
Default: true

Show spot finding results on the image

-
show_predictions
boolean
Default: false

Show Bragg spot predictions on the image (if available for the image)

-
show_beam_center
boolean
Default: true

Show beam center on the image

-
saturation
number <float> [ -32767 .. 32767 ]

Saturation value to set contrast in the preview image; if not provided, then autocontrast procedure is used

-
jpeg_quality
integer <int64> [ 0 .. 100 ]
Default: 100

Quality of JPEG image (100 - highest; 0 - lowest)

-
show_res_ring
number <float> [ 0.1 .. 100 ]
Default: 0.1

Show resolution ring, provided in Angstrom

-
color
string
Default: "indigo"
Enum: "indigo" "viridis" "bw" "wb" "green" "heat" "magma" "inferno"

Color scale for preview image

-
show_res_est
boolean
Default: false

Show resolution estimation as a ring

-

Responses

Response samples

Content type
application/json
{
  • "msg": "Detector in wrong state",
  • "reason": "WrongDAQState"
}

Get preview image in TIFF format

Authorizations:
bearerAuth
query Parameters
id
integer <int64> >= -2
Default: -1

Image ID in the image buffer. Special values: -1 - last image in the buffer, -2: last indexed image in the buffer

-

Responses

Clear image buffer

Turns off image buffer for the last data collection. Can be only run when Jungfraujoch is not collecting data.

-

Responses

Response samples

Content type
application/json
{
  • "msg": "Detector in wrong state",
  • "reason": "WrongDAQState"
}

Get status of the image buffers

Can be run at any stage of Jungfraujoch operation, including during data collection. -The status of the image buffer is volatile during data collection - if data collection goes for more images than available buffer slots, -then image might be replaced in the buffer between calling /images and /image.cbor.

-

Responses

Response samples

Content type
application/json
{
  • "min_image_number": 0,
  • "max_image_number": 0,
  • "image_numbers": [
    ],
  • "total_slots": 0,
  • "available_slots": 0,
  • "in_preparation_slots": 0,
  • "in_sending_slots": 0,
  • "current_counter": 0
}

Get Jungfraujoch version of jfjoch_broker

Responses

- diff --git a/docs/THIRD_PARTY_NOTICES.md b/docs/THIRD_PARTY_NOTICES.md index 6d94cbd35..13990f7b0 100644 --- a/docs/THIRD_PARTY_NOTICES.md +++ b/docs/THIRD_PARTY_NOTICES.md @@ -6,7 +6,8 @@ # Third-party software notices Jungfraujoch is licensed under **GPL-3.0** (see [`LICENSE`](LICENSE.md)); the FPGA design is -licensed under **CERN-OHL-S-2.0** (see [`fpga/LICENSE`](FPGA_LICENSE.md)). It builds on a number of +licensed under **CERN-OHL-S-2.0** (see [`fpga/LICENSE`](FPGA_LICENSE.md)), and the PCIe kernel driver +(`fpga/pcie_driver/`) under **GPL-2.0-or-later** (see [`fpga/pcie_driver/LICENSE`](https://gitea.psi.ch/mx/jungfraujoch/src/branch/main/fpga/pcie_driver/LICENSE)). It builds on a number of third-party components, acknowledged below as required by their licenses. This file is the human-readable manifest. The verbatim license texts live in the @@ -24,19 +25,21 @@ linked into the Jungfraujoch executables. | Component | Version | Copyright | License (SPDX) | License text | |---|---|---|---|---| | [spdlog](https://github.com/gabime/spdlog) | 1.17.0 | Gabi Melman | MIT | [spdlog.txt](https://gitea.psi.ch/mx/jungfraujoch/src/branch/main/licenses/spdlog.txt) | -| [Zstandard](https://github.com/facebook/zstd) | 1.5.7 | Meta Platforms, Inc. | BSD-3-Clause | [zstd.txt](https://gitea.psi.ch/mx/jungfraujoch/src/branch/main/licenses/zstd.txt) | +| [Zstandard](https://github.com/facebook/zstd) | 1.5.7 | Meta Platforms, Inc. | BSD-3-Clause OR GPL-2.0-only (used under BSD-3-Clause) | [zstd.txt](https://gitea.psi.ch/mx/jungfraujoch/src/branch/main/licenses/zstd.txt) | | [HDF5](https://github.com/HDFGroup/hdf5) | 2.2.0 | The HDF Group; UIUC | BSD-3-Clause-style + Apache-2.0 | [hdf5.txt](https://gitea.psi.ch/mx/jungfraujoch/src/branch/main/licenses/hdf5.txt) | | [slsDetectorPackage](https://github.com/slsdetectorgroup/slsDetectorPackage) | 8.0.2 / 9.2.0 | PSI | LGPL-3.0-or-later | [LGPL](https://gitea.psi.ch/mx/jungfraujoch/src/branch/main/licenses/slsDetectorPackage-LGPL-3.0.txt), [GPL](https://gitea.psi.ch/mx/jungfraujoch/src/branch/main/licenses/slsDetectorPackage-GPL-3.0.txt) | | [cpp-httplib](https://github.com/yhirose/cpp-httplib) | 0.56.0 | Yuji Hirose | MIT | [cpp-httplib.txt](https://gitea.psi.ch/mx/jungfraujoch/src/branch/main/licenses/cpp-httplib.txt) | | [libzmq (ZeroMQ)](https://github.com/zeromq/libzmq) | 4.3.5 | iMatix and contributors | MPL-2.0 | [libzmq.txt](https://gitea.psi.ch/mx/jungfraujoch/src/branch/main/licenses/libzmq.txt) | | [libtiff](https://gitlab.com/libtiff/libtiff) | 4.7.2 | Sam Leffler; SGI | libtiff (BSD-like) | [libtiff.txt](https://gitea.psi.ch/mx/jungfraujoch/src/branch/main/licenses/libtiff.txt) | | [FFTW](https://www.fftw.org/) | 3.3.10 | Matteo Frigo; MIT | GPL-2.0-or-later | [fftw.txt](https://gitea.psi.ch/mx/jungfraujoch/src/branch/main/licenses/fftw.txt) | -| [Ceres Solver](https://github.com/ceres-solver/ceres-solver) | (pinned) | Google Inc. and contributors | BSD-3-Clause | [ceres-solver.txt](https://gitea.psi.ch/mx/jungfraujoch/src/branch/main/licenses/ceres-solver.txt) | +| [Ceres Solver](https://github.com/ceres-solver/ceres-solver) | commit 0c70ed3a1a2d | Google Inc. and contributors | BSD-3-Clause | [ceres-solver.txt](https://gitea.psi.ch/mx/jungfraujoch/src/branch/main/licenses/ceres-solver.txt) | | [Abseil](https://github.com/abseil/abseil-cpp) | 20250127 (required by Ceres) | Google Inc. | Apache-2.0 | [abseil.txt](https://gitea.psi.ch/mx/jungfraujoch/src/branch/main/licenses/abseil.txt) | | [Mbed TLS](https://github.com/Mbed-TLS/mbedtls) (with TF-PSA-Crypto) | 4.2.0 | The Mbed TLS Contributors | Apache-2.0 OR GPL-2.0-or-later (used under Apache-2.0) | [mbedtls.txt](https://gitea.psi.ch/mx/jungfraujoch/src/branch/main/licenses/mbedtls.txt), [tf-psa-crypto.txt](https://gitea.psi.ch/mx/jungfraujoch/src/branch/main/licenses/tf-psa-crypto.txt) | | [Catch2](https://github.com/catchorg/Catch2) | 3.16.0 | Catch2 Authors | BSL-1.0 | [catch2.txt](https://gitea.psi.ch/mx/jungfraujoch/src/branch/main/licenses/catch2.txt) | | [zlib-ng](https://github.com/zlib-ng/zlib-ng) | 2.3.3 | Jean-loup Gailly and Mark Adler; the zlib-ng contributors | Zlib | [zlib.txt](https://gitea.psi.ch/mx/jungfraujoch/src/branch/main/licenses/zlib.txt) | | [Eigen](https://gitlab.com/libeigen/eigen) | 3.4.1 | Benoit Jacob, Gael Guennebaud and contributors | MPL-2.0 (+ BSD parts) | [eigen.txt](https://gitea.psi.ch/mx/jungfraujoch/src/branch/main/licenses/eigen.txt), [README](https://gitea.psi.ch/mx/jungfraujoch/src/branch/main/licenses/eigen-README.txt) | +| MD5 implementation (from OpenSSL), bundled in slsDetectorPackage | `slsSupportLib/src/md5.c` of slsDetectorPackage | The OpenSSL Project Authors; modifications PSI | Apache-2.0 | [slsDetectorPackage-md5-Apache-2.0.txt](https://gitea.psi.ch/mx/jungfraujoch/src/branch/main/licenses/slsDetectorPackage-md5-Apache-2.0.txt) | +| [RapidJSON](https://github.com/Tencent/rapidjson), bundled in slsDetectorPackage | `libs/rapidjson/` of slsDetectorPackage | THL A29 Limited, a Tencent company, and Milo Yip | MIT | [rapidjson.txt](https://gitea.psi.ch/mx/jungfraujoch/src/branch/main/licenses/rapidjson.txt) | Mbed TLS is fetched and statically linked only for viewer builds (`JFJOCH_VIEWER_BUILD` / `JFJOCH_VIEWER_ONLY`), where it is the TLS backend of `jfjoch_viewer`'s cpp-httplib client; the @@ -52,21 +55,26 @@ either way. Eigen is header-only: only its headers reach the binaries, and no Ei ## Vendored directly in the repository -These live in the source tree (see the path) rather than being fetched; traccc and the Ceres-derived minimiser are the exceptions - code adapted into first-party files rather than a vendored directory, see the notes at the end of this file. +These live in the source tree (see the path) rather than being fetched; traccc, the GEMMI-, Ceres- and fast-feedback-indexer-derived files and the Xilinx-derived HLS stream are the exceptions - code adapted into first-party files rather than a vendored directory, see the notes at the end of this file. | Component | Path | Copyright | License (SPDX) | License text | |---|---|---|---|---| -| [nlohmann/json](https://github.com/nlohmann/json) | `include/nlohmann/` | Niels Lohmann | MIT | [nlohmann-json.txt](https://gitea.psi.ch/mx/jungfraujoch/src/branch/main/licenses/nlohmann-json.txt) | +| [nlohmann/json](https://github.com/nlohmann/json) (3.12.0) | `include/nlohmann/` | Niels Lohmann | MIT | [nlohmann-json.txt](https://gitea.psi.ch/mx/jungfraujoch/src/branch/main/licenses/nlohmann-json.txt) | | [Macaron Base64](https://gist.github.com/tomykaira/f0fd86b6c73063283afe550bc5d77594) | `include/base64/` | tomykaira | MIT | [base64-macaron.txt](https://gitea.psi.ch/mx/jungfraujoch/src/branch/main/licenses/base64-macaron.txt) | -| [TinyCBOR](https://github.com/intel/tinycbor) | `frame_serialize/tinycbor/` | Intel Corporation | MIT | [tinycbor.txt](https://gitea.psi.ch/mx/jungfraujoch/src/branch/main/licenses/tinycbor.txt) | +| [TinyCBOR](https://github.com/intel/tinycbor) (0.6.0) | `frame_serialize/tinycbor/` | Intel Corporation | MIT | [tinycbor.txt](https://gitea.psi.ch/mx/jungfraujoch/src/branch/main/licenses/tinycbor.txt) | | [Bitshuffle](https://github.com/kiyo-masui/bitshuffle) | `compression/bitshuffle/` | Kiyoshi Masui | MIT | [bitshuffle.txt](https://gitea.psi.ch/mx/jungfraujoch/src/branch/main/licenses/bitshuffle.txt) | | [Bitshuffle (h-perf)](https://github.com/kalcutter/bitshuffle) | `compression/bitshuffle_hperf/` | Kal Conley | Apache-2.0 | [bitshuffle-hperf.txt](https://gitea.psi.ch/mx/jungfraujoch/src/branch/main/licenses/bitshuffle-hperf.txt) | -| [LZ4](https://github.com/lz4/lz4) | `compression/lz4/` | Yann Collet | BSD-2-Clause | [lz4.txt](https://gitea.psi.ch/mx/jungfraujoch/src/branch/main/licenses/lz4.txt) | +| [LZ4](https://github.com/lz4/lz4) (1.9.4) | `compression/lz4/` | Yann Collet | BSD-2-Clause | [lz4.txt](https://gitea.psi.ch/mx/jungfraujoch/src/branch/main/licenses/lz4.txt) | | [stb_image_write](https://github.com/nothings/stb) (v1.16, commit 31c1ad3) | `preview/stb/` | Sean Barrett | MIT OR Unlicense | [stb_image_write.txt](https://gitea.psi.ch/mx/jungfraujoch/src/branch/main/licenses/stb_image_write.txt) | | [HLS arbitrary-precision types](https://github.com/Xilinx/HLS_arbitrary_Precision_Types) | `fpga/include/` | Xilinx, Inc. | Apache-2.0 | [xilinx-hls-headers.txt](https://gitea.psi.ch/mx/jungfraujoch/src/branch/main/licenses/xilinx-hls-headers.txt) | +| Vitis HLS `hls_stream.h` (2023.1, adapted) | `fpga/hls/parallel_stream.h` | Xilinx, Inc. | Apache-2.0 | [xilinx-hls-headers.txt](https://gitea.psi.ch/mx/jungfraujoch/src/branch/main/licenses/xilinx-hls-headers.txt) | +| Vivado HLS `hls_burst_maxi.h` (simulation model of burst transfers on M-AXI, modified; to be removed when the FPGA part is frozen) | `fpga/include/hls_burst_maxi.h` | Xilinx, Inc. | not stated in the file; upstream terms not established | — | +| ICMP responder and IP header checksum (HPCN Group, UAM) | `fpga/hls/icmp.cpp`, `fpga/hls/ip_header_checksum.h` | HPCN Group, UAM Spain; modifications PSI | BSD-3-Clause | [hpcn-uam.txt](https://gitea.psi.ch/mx/jungfraujoch/src/branch/main/licenses/hpcn-uam.txt) | | [fast-feedback-indexer](https://github.com/paulscherrerinstitute/fast-feedback-indexer) (commit a94fd4f) | `image_analysis/indexing/fast-feedback-indexer/` | PSI | BSD-3-Clause | [fast-feedback-indexer.txt](https://gitea.psi.ch/mx/jungfraujoch/src/branch/main/licenses/fast-feedback-indexer.txt) | -| [GEMMI](https://github.com/project-gemmi/gemmi) | `gemmi_gph/` | Global Phasing Ltd. | MPL-2.0 | [gemmi.txt](https://gitea.psi.ch/mx/jungfraujoch/src/branch/main/licenses/gemmi.txt) | -| [CCP4 Monomer Library](https://github.com/MonomerLibrary/monomers) (subset: restraint dictionary data) | `image_analysis/structure_refinement/monomers/` | CCP4 / the Monomer Library authors (Vagin et al.) | LGPL-3.0-only | [ccp4-monomer-library.txt](https://gitea.psi.ch/mx/jungfraujoch/src/branch/main/licenses/ccp4-monomer-library.txt) | +| [GEMMI](https://github.com/project-gemmi/gemmi) (0.7.5, trimmed) | `gemmi_gph/` | Global Phasing Ltd. | MPL-2.0 | [gemmi.txt](https://gitea.psi.ch/mx/jungfraujoch/src/branch/main/licenses/gemmi.txt) | +| [stb_sprintf](https://github.com/nothings/stb) (v1.10, bundled with GEMMI) | `gemmi_gph/stb/stb_sprintf.h` | Jeff Roberts / RAD Game Tools; Sean Barrett | MIT OR Unlicense | [stb_sprintf.txt](https://gitea.psi.ch/mx/jungfraujoch/src/branch/main/licenses/stb_sprintf.txt) | +| 3x3 symmetric eigensolver (Connelly Barnes, after JAMA; bundled with GEMMI) | `gemmi_gph/eig3.cpp` | — | public domain (no SPDX id) | — | +| [CCP4 Monomer Library](https://github.com/MonomerLibrary/monomers) (modified subset: restraint dictionary data) | `image_analysis/structure_refinement/monomers/` | CCP4 / the Monomer Library authors (Vagin et al.) | LGPL-3.0-only | [ccp4-monomer-library.txt](https://gitea.psi.ch/mx/jungfraujoch/src/branch/main/licenses/ccp4-monomer-library.txt) | | [Larch](https://github.com/xraypy/xraylarch) (its Cromer-Liberman routines, as GEMMI ports them) | `gemmi_gph/fprime.cpp` | Matthew Newville, The University of Chicago, et al. | MIT | [larch.txt](https://gitea.psi.ch/mx/jungfraujoch/src/branch/main/licenses/larch.txt) | | [PEGTL](https://github.com/taocpp/PEGTL) | `gemmi_gph/gemmi/third_party/tao/` | Dr. Colin Hirsch and Daniel Frey | MIT | [pegtl.txt](https://gitea.psi.ch/mx/jungfraujoch/src/branch/main/licenses/pegtl.txt) | | [sajson](https://github.com/chadaustin/sajson) | `gemmi_gph/gemmi/third_party/sajson.h` | Chad Austin | MIT | [sajson.txt](https://gitea.psi.ch/mx/jungfraujoch/src/branch/main/licenses/sajson.txt) | @@ -77,6 +85,8 @@ These live in the source tree (see the path) rather than being fetched; traccc a | [traccc (ACTS)](https://github.com/acts-project/traccc) | `image_analysis/spot_finding/StrongPixelSet.cpp`, `SpotExtractorGPU.cu` | CERN, for the benefit of the ACTS project | MPL-2.0 | [traccc.txt](https://gitea.psi.ch/mx/jungfraujoch/src/branch/main/licenses/traccc.txt) | | [fast-feedback-indexer](https://github.com/paulscherrerinstitute/fast-feedback-indexer) (adapted) | `image_analysis/indexing/FFBIDXIndexerCPU.cpp` | PSI | BSD-3-Clause | [fast-feedback-indexer.txt](https://gitea.psi.ch/mx/jungfraujoch/src/branch/main/licenses/fast-feedback-indexer.txt) | | [Ceres Solver](https://github.com/ceres-solver/ceres-solver) (adapted) | `image_analysis/geom_refinement/LMSolver.h`, `LMSolver.cpp` | Google Inc. | BSD-3-Clause | [ceres-solver.txt](https://gitea.psi.ch/mx/jungfraujoch/src/branch/main/licenses/ceres-solver.txt) | +| [GEMMI](https://github.com/project-gemmi/gemmi) (adapted) | `image_analysis/structure_refinement/ModelScaling.cpp`, `ModelMaskGPU.cu`, `ModelStructureFactorsGPU.cpp`, `ModelDensityMetal.metal` | Global Phasing Ltd. | MPL-2.0 | [gemmi.txt](https://gitea.psi.ch/mx/jungfraujoch/src/branch/main/licenses/gemmi.txt) | +| [Durin](https://github.com/DiamondLightSource/durin) (adapted) | `xds-plugin/plugin.h`, `plugin.cpp` | Diamond Light Source Ltd.; Global Phasing Ltd. | BSD-3-Clause | [durin.txt](https://gitea.psi.ch/mx/jungfraujoch/src/branch/main/licenses/durin.txt) | | [xbflash.qspi](https://github.com/Xilinx/XRT) | `tools/xbflash.qspi/` | Xilinx / AMD | Apache-2.0 | [xbflash-qspi.txt](https://gitea.psi.ch/mx/jungfraujoch/src/branch/main/licenses/xbflash-qspi.txt) | | [wingetopt](https://github.com/alex85k/wingetopt) | `tools/wingetopt/` | Todd C. Miller; The NetBSD Foundation | ISC AND BSD-2-Clause | [wingetopt.txt](https://gitea.psi.ch/mx/jungfraujoch/src/branch/main/licenses/wingetopt.txt) | @@ -93,6 +103,19 @@ Not code and not linked into any binary: input files of the battery's timing ben The deposited entries are the reference models the benchmark's placements are checked against, and 4NWV's is also moved by a fixed transform at run time to make one start model. +## FPGA bitstreams + +The prebuilt FPGA images in `fpga/images/` (`jfjoch_fpga_pcie_100g.mcs.gz`, +`jfjoch_fpga_pcie_8x10g.mcs.gz`) are generated from the CERN-OHL-S-2.0 design together with AMD/Xilinx +IP cores, which are licensed by Xilinx under its own terms and not under CERN-OHL-S-2.0: + +| Component | Image | Copyright | Terms | +|---|---|---|---| +| UltraScale+ Integrated 100G Ethernet (CMAC) | `jfjoch_fpga_pcie_100g.mcs.gz` | AMD / Xilinx, Inc. | Xilinx IP licence ("Non-cost license ... has to be requested from AMD/Xilinx website", [docs/FPGA.md](FPGA.md)) | +| 10G/25G Ethernet Subsystem for UltraScale+ | `jfjoch_fpga_pcie_8x10g.mcs.gz` | AMD / Xilinx, Inc. | Xilinx IP licence, received by PSI from the Xilinx University Program; per [docs/FPGA.md](FPGA.md): "usage of bitstreams generated by PSI continuous integration pipeline for `8x10g` is only allowed for non-commercial use" | + +Both images also contain the IP cores included with Vivado, under Xilinx's terms. + ## Runtime libraries and SDKs (shipped in binaries, not in the source tree) | Component | Used by | License | Notice | @@ -135,16 +158,31 @@ served frontend, so the shipped web UI carries its own attribution. * **fast-feedback-indexer** is also vendored and linked in CUDA builds (table above); separately, `FFBIDXIndexerCPU.cpp` ports its CUDA kernels to the CPU. The file names the origin at the top and is covered by `licenses/fast-feedback-indexer.txt`. +* **GEMMI** is also vendored (table above); separately, `ModelScaling.cpp`, `ModelMaskGPU.cu`, + `ModelStructureFactorsGPU.cpp` and `ModelDensityMetal.metal` in `image_analysis/structure_refinement/` + follow GEMMI's scaling, Levenberg-Marquardt, solvent-mask, reciprocal-grid and form-factor code. + Each names the GEMMI source it follows and is covered by `licenses/gemmi.txt`. +* **Durin** (`xds-plugin/plugin.h`/`.cpp`): the XDS plugin's entry points are based on the Durin plugin + of Diamond Light Source and Global Phasing; both files name the origin at the top and are covered by + `licenses/durin.txt`. +* **slsDetectorPackage's bundled code**: the slsDetectorPackage sources compiled into the binaries + include an MD5 implementation taken from OpenSSL (Apache-2.0) and the RapidJSON headers (MIT); their + `msinttypes/` headers (BSD-3-Clause) are for old MSVC compilers only. * **FFTW** is GPL-2.0-or-later — compatible with, and absorbed by, this project's GPL-3.0 license. * **Apache-2.0** components: where upstream ships a `NOTICE` file, it is reproduced in the corresponding `licenses/` text. * **CCP4 Monomer Library (LGPL-3.0)** is data, not code: the restraint dictionaries of the compounds - rugnux's refinement restrains, copied unmodified per compound into - `image_analysis/structure_refinement/monomers/` (`links_and_mods.cif` and `ener_lib.cif` cut down to - the entries those compounds use, and the library's metal-site distances of `metals.json` for its ions as - `metals.cif`), with the library's own `COPYING`. The build embeds them in the binary - as text, and `image_analysis/structure_refinement/monomers/update_monomers.py` regenerates the subset from the upstream library, so the - copy can be replaced by a user with a version of their own. + rugnux's refinement restrains, in `image_analysis/structure_refinement/monomers/`, with the library's + own `COPYING`. The subset is a **modified** version of the library: the per-compound files are copied + unmodified, while `links_and_mods.cif` and `ener_lib.cif` are cut down to the entries those compounds + use and `metals.json` is converted to `metals.cif` holding only the metal-site distances of its ions. + Each of these three files says so in a comment at its top, with the date it was generated. + `image_analysis/structure_refinement/monomers/update_monomers.py` regenerates the subset from the + upstream library. The build embeds the files in the binary as text. As the LGPL-3.0 requires, the + modified files remain under LGPL-3.0 (with the GPL-3.0 text in `LICENSE`), the source tree carries + them in their preferred (text) form together with the script that makes them, and a user can replace + the embedded copy with a version of their own by replacing the files in that directory (or rerunning + the script on another library version) and rebuilding. * **Qt (LGPL-3.0)** and **NVIDIA CUDA (EULA)** carry redistribution conditions beyond a copyright notice; see their dedicated notice files. The verbatim LGPL-3.0 and CUDA EULA texts are bundled (`licenses/Qt6-LGPL-3.0.txt`, `licenses/NVIDIA-CUDA-EULA.txt`); the CUDA EULA is the one shipped diff --git a/docs/conf.py b/docs/conf.py index 2bad618af..a86991759 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -12,7 +12,7 @@ project = 'Jungfraujoch' copyright = '2024, Paul Scherrer Institute' author = 'Filip Leonarski' -release = '1.0.0-rc.186' +release = '1.0.0' # -- General configuration --------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration diff --git a/docs/python_client/README.md b/docs/python_client/README.md index 2a5ae315a..b76b02d91 100644 --- a/docs/python_client/README.md +++ b/docs/python_client/README.md @@ -22,8 +22,8 @@ communicate through network calls or other mechanisms. This Python package is automatically generated by the [OpenAPI Generator](https://openapi-generator.tech) project: -- API version: 1.0.0-rc.186 -- Package version: 1.0.0-rc.186 +- API version: 1.0.0 +- Package version: 1.0.0 - Generator version: 7.20.0 - Build package: org.openapitools.codegen.languages.PythonClientCodegen diff --git a/fpga/hdl/action_config.v b/fpga/hdl/action_config.v index 0ddaaa0be..c2e549417 100644 --- a/fpga/hdl/action_config.v +++ b/fpga/hdl/action_config.v @@ -10,7 +10,7 @@ localparam signed [31:0] INT32_MIN = 32'sh80000000; `define JFJOCH_FPGA_MAJOR_VERSION 8'd1 `define JFJOCH_FPGA_MINOR_VERSION 8'd0 `define JFJOCH_FPGA_PATCH_VERSION 8'd0 -`define JFJOCH_FPGA_PRERELEASE 64'h3638312E6372 +`define JFJOCH_FPGA_PRERELEASE 64'h0 `define GIT_SHA1 32'h `define MAX_MODULES_FPGA 32'd16 diff --git a/fpga/pcie_driver/dkms.conf b/fpga/pcie_driver/dkms.conf index b76d9ef1f..455ca92c9 100644 --- a/fpga/pcie_driver/dkms.conf +++ b/fpga/pcie_driver/dkms.conf @@ -2,7 +2,7 @@ # SPDX-License-Identifier: GPL-2.0-or-later PACKAGE_NAME=jfjoch -PACKAGE_VERSION=1.0.0-rc.186 +PACKAGE_VERSION=1.0.0 DEST_MODULE_LOCATION=/extra BUILT_MODULE_NAME=jfjoch diff --git a/fpga/pcie_driver/install_dkms.sh b/fpga/pcie_driver/install_dkms.sh index 4f6d5c267..a4e289f3c 100755 --- a/fpga/pcie_driver/install_dkms.sh +++ b/fpga/pcie_driver/install_dkms.sh @@ -3,7 +3,7 @@ # SPDX-FileCopyrightText: 2024 Filip Leonarski, Paul Scherrer Institute # SPDX-License-Identifier: GPL-2.0-or-later -VERSION=1.0.0-rc.186 +VERSION=1.0.0 mkdir -p /usr/src/jfjoch-${VERSION}/src cp dkms.conf /usr/src/jfjoch-${VERSION} diff --git a/fpga/pcie_driver/jfjoch_drv.c b/fpga/pcie_driver/jfjoch_drv.c index ed2675ed1..a03529649 100644 --- a/fpga/pcie_driver/jfjoch_drv.c +++ b/fpga/pcie_driver/jfjoch_drv.c @@ -12,7 +12,7 @@ MODULE_AUTHOR("Filip Leonarski; Paul Scherrer Institute"); MODULE_DESCRIPTION("Jungfraujoch device module"); MODULE_LICENSE("GPL"); -MODULE_VERSION("1.0.0-rc.186"); +MODULE_VERSION("1.0.0"); #define PCI_DEV_ID_JUNGFRAUJOCH (0x3450) diff --git a/fpga/pcie_driver/postinstall.sh b/fpga/pcie_driver/postinstall.sh index 15b0ee0d5..6aaf70149 100755 --- a/fpga/pcie_driver/postinstall.sh +++ b/fpga/pcie_driver/postinstall.sh @@ -1,7 +1,7 @@ #!/bin/bash # Taken from https://schneide.blog/2015/08/10/packaging-kernel-modulesdrivers-using-dkms/ -VERSION=1.0.0-rc.186 +VERSION=1.0.0 occurrences=`/usr/sbin/dkms status | grep jfjoch | grep ${VERSION} | wc -l` diff --git a/fpga/pcie_driver/preuninstall.sh b/fpga/pcie_driver/preuninstall.sh index f8d8172b5..a1101148f 100755 --- a/fpga/pcie_driver/preuninstall.sh +++ b/fpga/pcie_driver/preuninstall.sh @@ -1,7 +1,7 @@ #!/bin/bash # Taken from https://schneide.blog/2015/08/10/packaging-kernel-modulesdrivers-using-dkms/ -VERSION=1.0.0-rc.186 +VERSION=1.0.0 /usr/sbin/dkms remove -m jfjoch -v ${VERSION} --all diff --git a/frontend/package-lock.json b/frontend/package-lock.json index 5668d0a20..d2699a6df 100644 --- a/frontend/package-lock.json +++ b/frontend/package-lock.json @@ -1,12 +1,12 @@ { "name": "jungfraujoch-frontend", - "version": "1.0.0-rc.186", + "version": "1.0.0", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "jungfraujoch-frontend", - "version": "1.0.0-rc.186", + "version": "1.0.0", "license": "GPL-3.0", "dependencies": { "@emotion/react": "^11.10.4", diff --git a/frontend/package.json b/frontend/package.json index 109574de9..196488a2d 100644 --- a/frontend/package.json +++ b/frontend/package.json @@ -1,6 +1,6 @@ { "name": "jungfraujoch-frontend", - "version": "1.0.0-rc.186", + "version": "1.0.0", "license": "GPL-3.0", "private": true, "homepage": "/frontend", diff --git a/frontend/src/version.ts b/frontend/src/version.ts index 7e944496e..3f38c9c7d 100644 --- a/frontend/src/version.ts +++ b/frontend/src/version.ts @@ -3,4 +3,4 @@ * SPDX-License-Identifier: GPL-3.0-only */ -export const JFJOCH_VERSION : string = "1.0.0-rc.186"; \ No newline at end of file +export const JFJOCH_VERSION : string = "1.0.0"; \ No newline at end of file -- 2.54.1 From c695c45c6ef4c1c166b586d3e8e3637a1ffb4d01 Mon Sep 17 00:00:00 2001 From: Filip Leonarski Date: Sun, 15 Nov 2026 17:01:47 +0100 Subject: [PATCH 083/229] Changelog: the release is 1.0.0 Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01UqXYdJDrM65gxsCn2PrbfK --- docs/CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index 4a8b2c674..0a7be9016 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -1,7 +1,7 @@ # Changelog ## 1.0.0 -### 1.0.0-rc.187 +### 1.0.0 * Rugnux: A unit cell and space group given with `-C`/`-S` are kept from indexing to merging, in the given setting; the angles typed with `-C` are read literally and, without `-S`, fix the crystal system they name. * Rugnux: `--mode scale` merges several stills `_process.h5` files as one run; more stable rocking-width estimates for stills, and another crystal form found next to a given cell is reported. -- 2.54.1 From 121e26ceae523729cacecfc3c5ceb4e7e86ce1de Mon Sep 17 00:00:00 2001 From: Filip Leonarski Date: Sun, 15 Nov 2026 17:01:47 +0100 Subject: [PATCH 084/229] Download links stay on the release the documentation was built for The download pages and the landing page were rendered with links for `release`, but the page script then repointed every button at the newest Gitea release, so a later release candidate would have moved the 1.0.0 documentation's links. The script now looks up the release tagged with the page's own version (releases/tags/); if it is not published, the built-in links stand. The install examples name 1.0.0 instead of an rc. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01UqXYdJDrM65gxsCn2PrbfK --- README.md | 2 +- docs/RUGNUX.md | 2 +- docs/RUGNUX_INSTALL.md | 2 +- docs/_ext/jfjoch_downloads.py | 4 ++-- docs/_static/jfjoch_downloads.js | 22 +++++++++++----------- docs/conf.py | 2 +- 6 files changed, 17 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index e68e1741a..ef41d23df 100644 --- a/README.md +++ b/README.md @@ -48,7 +48,7 @@ Rugnux is one executable in an archive on the release page, it into a directory of its own. On Linux x86-64, with or without an NVIDIA GPU: ``` -VERSION=1.0.0-rc.184 # the newest release on the page +VERSION=1.0.0 curl -L -O https://gitea.psi.ch/mx/jungfraujoch/releases/download/$VERSION/rugnux-$VERSION-linux-x86_64-cuda12.tgz mkdir -p rugnux-$VERSION && tar xzf rugnux-$VERSION-linux-x86_64-cuda12.tgz -C rugnux-$VERSION export PATH=$PWD/rugnux-$VERSION/bin:$PATH diff --git a/docs/RUGNUX.md b/docs/RUGNUX.md index b426e829a..1696fea56 100644 --- a/docs/RUGNUX.md +++ b/docs/RUGNUX.md @@ -53,7 +53,7 @@ Rugnux is one executable in an archive on the release page, https://gitea.psi.ch On Linux x86-64 (the other platforms are on [Download](RUGNUX_DOWNLOAD.md)): ``` -VERSION=1.0.0-rc.184 +VERSION=1.0.0 curl -L -O https://gitea.psi.ch/mx/jungfraujoch/releases/download/$VERSION/rugnux-$VERSION-linux-x86_64-cuda12.tgz mkdir -p rugnux-$VERSION && tar xzf rugnux-$VERSION-linux-x86_64-cuda12.tgz -C rugnux-$VERSION export PATH=$PWD/rugnux-$VERSION/bin:$PATH diff --git a/docs/RUGNUX_INSTALL.md b/docs/RUGNUX_INSTALL.md index a9b2d74be..7d7ac0af9 100644 --- a/docs/RUGNUX_INSTALL.md +++ b/docs/RUGNUX_INSTALL.md @@ -40,7 +40,7 @@ release page: give `tar` a destination of its own, or it will scatter those into whatever directory you are in: ``` -VERSION=1.0.0-rc.184 # the newest release on the page +VERSION=1.0.0 curl -L -O https://gitea.psi.ch/mx/jungfraujoch/releases/download/$VERSION/rugnux-$VERSION-linux-x86_64-cuda12.tgz mkdir -p /opt/rugnux-$VERSION tar xzf rugnux-$VERSION-linux-x86_64-cuda12.tgz -C /opt/rugnux-$VERSION diff --git a/docs/_ext/jfjoch_downloads.py b/docs/_ext/jfjoch_downloads.py index 5fed0c762..ce22b1ecd 100644 --- a/docs/_ext/jfjoch_downloads.py +++ b/docs/_ext/jfjoch_downloads.py @@ -7,8 +7,8 @@ archive. Every link is built from the version Sphinx was configured with (``release`` in docs/conf.py, which update_version.sh rewrites from VERSION), so no version string on the page is maintained by hand. The page's script (_static/jfjoch_downloads.js) then asks the Gitea API for the -newest published release and repoints the buttons at its assets - so a docs build older or newer -than the current release still offers the archives that exist, and says which ones do not. +release tagged with that same version and checks the buttons against its assets (URL, size, and +which platforms it lacks); later releases never move the links. The asset names follow CPack's naming in CMakeLists.txt; the regular expressions are what the script matches against the release's asset list, written loosely enough to survive a CUDA major diff --git a/docs/_static/jfjoch_downloads.js b/docs/_static/jfjoch_downloads.js index 8aaac7a54..ed4c16457 100644 --- a/docs/_static/jfjoch_downloads.js +++ b/docs/_static/jfjoch_downloads.js @@ -1,23 +1,24 @@ // SPDX-FileCopyrightText: 2026 Filip Leonarski, Paul Scherrer Institute // SPDX-License-Identifier: GPL-3.0-only -// Download pages: repoint the buttons at the newest published release. +// Download pages: check the buttons against the release the documentation was built for. // -// The page is rendered with links for the version the documentation was built for -// (docs/_ext/jfjoch_downloads.py). That version may not be released yet, or may be behind the -// current release, so once the page is up this asks the Gitea API (anonymous, CORS-enabled) for -// the newest non-draft release and rewrites each button from that release's asset list: the -// matching asset's URL and size, or "not part of this release" where the platform has none. -// Without network access, or if the API answers anything but 200, the built-in links stand. +// The page is rendered with links for that version (docs/_ext/jfjoch_downloads.py). Once the page +// is up this asks the Gitea API (anonymous, CORS-enabled) for the release tagged with exactly that +// version - never the newest one, so later releases do not move the links - and rewrites each +// button from its asset list: the matching asset's URL and size, or "not part of this release" +// where the platform has none. Without network access, or if the API answers anything but 200 +// (the release is not published yet), the built-in links stand. (function main() { // Sphinx puts html_js_files into , before the page's body exists. if (document.readyState === "loading") { document.addEventListener("DOMContentLoaded", main); return; } - var API = "https://gitea.psi.ch/api/v1/repos/mx/jungfraujoch/releases?limit=10"; var blocks = document.querySelectorAll(".jfj-dl"); if (!blocks.length || !window.fetch) return; + var version = blocks[0].querySelector("[data-jfj=version]").textContent; + var API = "https://gitea.psi.ch/api/v1/repos/mx/jungfraujoch/releases/tags/" + encodeURIComponent(version); function megabytes(bytes) { return (bytes / 1048576).toFixed(bytes < 10485760 ? 1 : 0) + " MB"; @@ -50,9 +51,8 @@ fetch(API) .then(function (r) { return r.ok ? r.json() : Promise.reject(r.status); }) - .then(function (releases) { - var release = releases.filter(function (r) { return !r.draft && r.assets; })[0]; - if (release) apply(release); + .then(function (release) { + if (!release.draft && release.assets) apply(release); }) .catch(function () { /* offline or API unavailable: the built-in links stand */ }); })(); diff --git a/docs/conf.py b/docs/conf.py index a86991759..1eff4cff1 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -71,7 +71,7 @@ mathjax3_config = { html_theme = 'sphinx_material' html_static_path = ['../broker/redoc-static.html', '_static'] # The home page's program cards and the download pages' buttons (docs/_static); the script asks -# the Gitea API for the newest release and repoints the download buttons at its assets. +# the Gitea API for the release of this `release` version and checks the buttons against its assets. html_css_files = ['jfjoch.css'] html_js_files = ['jfjoch_downloads.js'] #html_theme_options = { -- 2.54.1 From c125a516b4c0940b108bf4504fc80f2ba8dac520 Mon Sep 17 00:00:00 2001 From: Filip Leonarski Date: Sun, 15 Nov 2026 17:11:51 +0100 Subject: [PATCH 085/229] rugnux: a crystal system fixed by -C bounds the space-group search With -C and no -S the typed angles fix the crystal system and the indexer holds the lattice in it, but the metric-lattice re-ask after the P1 merge could still reindex into a higher class the metric offers and adopt a group there (a cell typed with one angle at 90.03 fixed monoclinic, indexed monoclinic, and ended tetragonal). That re-ask only ever commits a strictly higher point group, so it is skipped when the system is fixed, as the centred-group reduction already is; the search then stays within the system the cell names, as docs/RUGNUX_CLI.md states. Runs without a fixed system (no -C, a measured cell, or -S) are unaffected. Verified: that cell now ends P 1 1 21; -C with 90/90/90 still P 41 21 2 and a monoclinic -C on a C2 set still C 1 2 1, both with p.hkl byte-identical to the rc187 binary. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01UqXYdJDrM65gxsCn2PrbfK --- rugnux/RugnuxScaleMerge.cpp | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/rugnux/RugnuxScaleMerge.cpp b/rugnux/RugnuxScaleMerge.cpp index 96a3b7d7d..da3719339 100644 --- a/rugnux/RugnuxScaleMerge.cpp +++ b/rugnux/RugnuxScaleMerge.cpp @@ -2836,7 +2836,11 @@ bool Rugnux::ScaleMergeAndSymmetry(PipelineLocals &p) { // answered by its having run. The two cannot disagree: the ask below only ever replaces the // answer in hand with a STRICTLY higher point group, and it writes all four commit_ values // together, so the group, the cell and the lattice type stay one answer. - if (end_msg.rotation_lattice.has_value() && end_msg.rotation_lattice_type.has_value()) { + // + // A cell given with -C fixes the crystal system, and the indexer already holds it there, so + // a higher class is never asked: the search stays within the system the cell names. + if (end_msg.rotation_lattice.has_value() && end_msg.rotation_lattice_type.has_value() + && !experiment_.GetIndexingSettings().GetFixedLatticeSystem()) { TimingMark metric_mark(logger, "metric lattice re-ask"); // The merge is indexed on the lattice the indexer named, whatever has been committed // since, so the metric is measured on the primitive form of THAT one. -- 2.54.1 From 04baa16060098db38e62a5bc930ae30b709f0f32 Mon Sep 17 00:00:00 2001 From: Filip Leonarski Date: Sun, 15 Nov 2026 21:23:40 +0100 Subject: [PATCH 086/229] CPU FFTs on pocketfft instead of FFTW (prototype) Every CPU FFT site - the FFT indexer's batched 1D r2c, the beam-centre 2D r2c/c2r, the model-path 3D transforms (MapToFPhi, MapFromFPhi(Execute), MapToFPhiInParallel), the tNCS Patterson c2r and the viewer's 1D chart - goes through common/CpuFFT, a plan-free wrapper over the pocketfft header already vendored with gemmi. The header is included under a namespace of its own: gemmi includes it with POCKETFFT_NO_MULTITHREADING, and the linker otherwise merges the two sets of templates (MapToFPhiInParallel with 4 threads gave garbage until it was renamed). MapToFPhiInParallel uses pocketfft's own threads (one call per stage) instead of a ParallelFor over FFTW plans. The programs no longer link fftw3f; FFTW stays fetched for jfjoch_test only, where [fft] checks pocketfft against it (rel. error < 1e-5). Measured (Ryzen 5950X, --no-gpu -N 16, one run each, against rc187 aa898ac0f): cytc_x10sa --model --no-refine 100.7 -> 99.5 s; euxfel83 first 6 files --no-refine 81.7 -> 83.3 s (noise level); full cytc refinement 1514 -> ~1399 s. Merged results identical (same hkl md5, SG, cell, R-work/R-free/CC of model validation). Microbench, single thread, FFTW_ESTIMATE as the call sites plan: pocketfft 0.4-0.6x FFTW's time on the 2D/3D shapes; with FFTW_MEASURE the two are equal on 3D. Indexer length 3142 = 2 x 1571 is 2.4x SLOWER on pocketfft (Bluestein); a smooth length (3150) is 0.06 s vs FFTW's 0.25 s at 3142. BeamCenterFFTGPU_MatchesTheCPUEngine: gate mismatches over 4M centres on the threshold 7 (FFTW) -> 17 (pocketfft); bound raised to 30. pocketfft's float error is FFTW's or lower (rms 1.4e-7 vs 1.5e-7 against double). Known: "A near-extinct class is reported as a sub-lattice" [tncs] fails - its synthetic reads modulation 20.0x against a 20.0x gate; FFT rounding tips it. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01UqXYdJDrM65gxsCn2PrbfK --- CMakeLists.txt | 5 +- common/CMakeLists.txt | 1 + common/CpuFFT.cpp | 70 +++++++++ common/CpuFFT.h | 36 +++++ common/FFTWPlannerLock.h | 14 -- .../geom_refinement/BeamCenterFFT.h | 2 +- .../geom_refinement/BeamCenterFFTCPU.cpp | 32 +---- .../geom_refinement/BeamCenterFFTCPU.h | 2 +- .../geom_refinement/BeamCenterFFTEngine.h | 2 +- image_analysis/geom_refinement/CMakeLists.txt | 4 +- image_analysis/indexing/CMakeLists.txt | 3 +- image_analysis/indexing/FFTIndexerCPU.cpp | 36 +---- image_analysis/indexing/FFTIndexerCPU.h | 13 +- image_analysis/scale_merge/CMakeLists.txt | 2 +- .../scale_merge/TranslationalNCS.cpp | 38 ++--- .../structure_refinement/CMakeLists.txt | 2 +- .../structure_refinement/ModelFFT.cpp | 135 ++++-------------- .../structure_refinement/ModelFFT.h | 19 +-- .../MolecularReplacement.cpp | 14 +- .../structure_refinement/RefinementXray.cpp | 10 +- rugnux/CMakeLists.txt | 2 +- rugnux/rugnux_cli.cpp | 15 -- tests/BeamCenterFFTGPUTest.cpp | 5 +- tests/CMakeLists.txt | 3 +- tests/CpuFFTTest.cpp | 117 +++++++++++++++ viewer/CMakeLists.txt | 2 +- viewer/charts/JFJochDatasetInfoChartView.cpp | 22 +-- viewer/charts/JFJochDatasetInfoChartView.h | 4 - 28 files changed, 308 insertions(+), 302 deletions(-) create mode 100644 common/CpuFFT.cpp create mode 100644 common/CpuFFT.h delete mode 100644 common/FFTWPlannerLock.h create mode 100644 tests/CpuFFTTest.cpp diff --git a/CMakeLists.txt b/CMakeLists.txt index b17e90199..eae9a9287 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -474,8 +474,9 @@ FetchContent_Declare(tiff EXCLUDE_FROM_ALL) FetchContent_MakeAvailable(tiff) -# FFTW single precision (target fftw3f): the CPU fallback indexer, enables JFJOCH_USE_FFTW. -# Built from the release tarball -- the git repo ships no pre-generated codelets (needs the +# FFTW single precision (target fftw3f): no longer used by the programs, whose CPU FFTs are pocketfft's +# (common/CpuFFT) - linked only by jfjoch_test, which checks pocketfft against it. JFJOCH_USE_FFTW still +# means "the CPU FFT indexer is built". Built from the release tarball -- the git repo ships no pre-generated codelets (needs the # OCaml genfft). SET(ENABLE_FLOAT ON CACHE BOOL "" FORCE) SET(BUILD_TESTS OFF CACHE BOOL "" FORCE) diff --git a/common/CMakeLists.txt b/common/CMakeLists.txt index 97d641f1a..767c4f2b7 100644 --- a/common/CMakeLists.txt +++ b/common/CMakeLists.txt @@ -76,6 +76,7 @@ ADD_LIBRARY(JFJochZMQ STATIC ZMQWrappers.cpp ZMQWrappers.h) ADD_LIBRARY(JFJochCommon STATIC Coord.cpp Coord.h + CpuFFT.cpp CpuFFT.h DiffractionExperiment.cpp DiffractionExperiment.h RawToConvertedGeometry.h JFJochException.h diff --git a/common/CpuFFT.cpp b/common/CpuFFT.cpp new file mode 100644 index 000000000..6085fc0d3 --- /dev/null +++ b/common/CpuFFT.cpp @@ -0,0 +1,70 @@ +// SPDX-FileCopyrightText: 2026 Filip Leonarski, Paul Scherrer Institute +// SPDX-License-Identifier: GPL-3.0-only + +#include "CpuFFT.h" + +// Under a name of its own: gemmi includes the same header with POCKETFFT_NO_MULTITHREADING, and its +// templates and ours must not be merged by the linker into one (single-threaded or not) copy. +#define pocketfft jfjoch_pocketfft +#include "../gemmi_gph/gemmi/third_party/pocketfft_hdronly.h" + +namespace cpu_fft { + +namespace { + +// pocketfft counts strides in bytes. +pocketfft::stride_t Bytes(const Strides &s, size_t element) { + pocketfft::stride_t out(s.size()); + for (size_t i = 0; i < s.size(); i++) + out[i] = s[i] * static_cast(element); + return out; +} + +Strides Contiguous(const Shape &shape) { + Strides s(shape.size()); + std::ptrdiff_t step = 1; + for (size_t i = shape.size(); i-- > 0;) { + s[i] = step; + step *= static_cast(shape[i]); + } + return s; +} + +Shape Halved(Shape shape, size_t axis) { + shape[axis] = shape[axis] / 2 + 1; + return shape; +} + +} // namespace + +void R2C(const Shape &shape, const Strides &stride_in, const Strides &stride_out, const Shape &axes, + const float *in, std::complex *out, size_t nthreads) { + pocketfft::r2c(shape, Bytes(stride_in, sizeof(float)), Bytes(stride_out, sizeof(std::complex)), + axes, pocketfft::FORWARD, in, out, 1.0f, nthreads); +} + +void R2C(const Shape &shape, const Shape &axes, const float *in, std::complex *out, size_t nthreads) { + R2C(shape, Contiguous(shape), Contiguous(Halved(shape, axes.back())), axes, in, out, nthreads); +} + +void C2R(const Shape &shape, const Shape &axes, std::complex *in, float *out, size_t nthreads) { + const Shape half = Halved(shape, axes.back()); + const pocketfft::stride_t stride_in = Bytes(Contiguous(half), sizeof(std::complex)); + if (axes.size() > 1) + pocketfft::c2c(half, stride_in, stride_in, Shape(axes.begin(), axes.end() - 1), pocketfft::BACKWARD, + in, in, 1.0f, nthreads); + pocketfft::c2r(shape, stride_in, Bytes(Contiguous(shape), sizeof(float)), axes.back(), + pocketfft::BACKWARD, in, out, 1.0f, nthreads); +} + +void C2C(const Shape &shape, const Strides &stride, const Shape &axes, bool forward, std::complex *data, + size_t nthreads) { + const pocketfft::stride_t s = Bytes(stride, sizeof(std::complex)); + pocketfft::c2c(shape, s, s, axes, forward, data, data, 1.0f, nthreads); +} + +void C2C(const Shape &shape, const Shape &axes, bool forward, std::complex *data, size_t nthreads) { + C2C(shape, Contiguous(shape), axes, forward, data, nthreads); +} + +} // namespace cpu_fft diff --git a/common/CpuFFT.h b/common/CpuFFT.h new file mode 100644 index 000000000..c1cebdb61 --- /dev/null +++ b/common/CpuFFT.h @@ -0,0 +1,36 @@ +// SPDX-FileCopyrightText: 2026 Filip Leonarski, Paul Scherrer Institute +// SPDX-License-Identifier: GPL-3.0-only + +#pragma once + +#include +#include +#include + +// Single-precision CPU FFTs on pocketfft (the header vendored with gemmi). There are no plans to make: +// every call is a whole transform, safe from several threads at once. +// +// Arrays are row-major (the last axis fastest) and the transforms unnormalised, the forward one with +// exp(-2 pi i k.x), as FFTW's. A real transform halves the last axis in `axes` (n/2 + 1 complex values +// along it). Strides count elements of the array they belong to - floats on the real side, complex values +// on the complex side; without them the array is contiguous. `nthreads` splits one transform's lines. +namespace cpu_fft { + +using Shape = std::vector; +using Strides = std::vector; + +// Real -> complex, forward. `shape` is the real array's. +void R2C(const Shape &shape, const Strides &stride_in, const Strides &stride_out, const Shape &axes, + const float *in, std::complex *out, size_t nthreads = 1); +void R2C(const Shape &shape, const Shape &axes, const float *in, std::complex *out, size_t nthreads = 1); + +// Complex -> real, backward (exp(+2 pi i k.x)). `shape` is the real array's. `in` is overwritten, as by +// FFTW's c2r: the complex axes are transformed in place before the real one. +void C2R(const Shape &shape, const Shape &axes, std::complex *in, float *out, size_t nthreads = 1); + +// Complex -> complex, in place. +void C2C(const Shape &shape, const Strides &stride, const Shape &axes, bool forward, std::complex *data, + size_t nthreads = 1); +void C2C(const Shape &shape, const Shape &axes, bool forward, std::complex *data, size_t nthreads = 1); + +} // namespace cpu_fft diff --git a/common/FFTWPlannerLock.h b/common/FFTWPlannerLock.h deleted file mode 100644 index a432b7971..000000000 --- a/common/FFTWPlannerLock.h +++ /dev/null @@ -1,14 +0,0 @@ -// SPDX-FileCopyrightText: 2026 Filip Leonarski, Paul Scherrer Institute -// SPDX-License-Identifier: GPL-3.0-only - -#pragma once - -#include - -// FFTW's planner - every fftwf_plan_* and fftwf_destroy_plan call - shares global state and is not -// thread-safe; executing a plan is. So every piece of code that makes or destroys a plan takes this -// one lock, not a lock of its own: two private locks do not stop two planners running at once. -inline std::mutex &FFTWPlannerMutex() { - static std::mutex m; - return m; -} diff --git a/image_analysis/geom_refinement/BeamCenterFFT.h b/image_analysis/geom_refinement/BeamCenterFFT.h index 4092b3be9..0ec907e10 100644 --- a/image_analysis/geom_refinement/BeamCenterFFT.h +++ b/image_analysis/geom_refinement/BeamCenterFFT.h @@ -30,7 +30,7 @@ // The input is the mean-projection the pre-scan already accumulates for the beam-stop search // (ShadowFinder::GetMeanProjection), NAN where nothing was counted - so this costs no new I/O. // -// The transforms run on the GPU where there is one with room for them and on fftw3f otherwise +// The transforms run on the GPU where there is one with room for them and on the CPU (pocketfft) otherwise // (BeamCenterFFTGPU / BeamCenterFFTCPU); everything that decides anything is shared between the // two. Whole-detector reach is what this buys, and on a 16 Mpixel detector the transforms are the // whole of its cost, so which engine runs them is the difference between seconds and milliseconds. diff --git a/image_analysis/geom_refinement/BeamCenterFFTCPU.cpp b/image_analysis/geom_refinement/BeamCenterFFTCPU.cpp index 1496752f5..52ca18938 100644 --- a/image_analysis/geom_refinement/BeamCenterFFTCPU.cpp +++ b/image_analysis/geom_refinement/BeamCenterFFTCPU.cpp @@ -8,12 +8,8 @@ #include #include #include -#include -#include -#include - -#include "../../common/FFTWPlannerLock.h" +#include "../../common/CpuFFT.h" namespace { @@ -21,8 +17,6 @@ namespace { class Rfft2 { int64_t ny, nx, nxc; std::vector real; - fftwf_plan fwd = nullptr; - fftwf_plan bwd = nullptr; public: std::vector> spectrum; @@ -30,24 +24,6 @@ public: Rfft2(int64_t ny_, int64_t nx_) : ny(ny_), nx(nx_), nxc(nx_ / 2 + 1) { real.resize(static_cast(ny * nx)); spectrum.resize(static_cast(ny * nxc)); - std::unique_lock lock(FFTWPlannerMutex()); - fwd = fftwf_plan_dft_r2c_2d(static_cast(ny), static_cast(nx), real.data(), - reinterpret_cast(spectrum.data()), - FFTW_ESTIMATE); - bwd = fftwf_plan_dft_c2r_2d(static_cast(ny), static_cast(nx), - reinterpret_cast(spectrum.data()), - real.data(), FFTW_ESTIMATE); - if (!fwd || !bwd) - throw std::runtime_error("BeamCenterFFT: fftwf plan failed"); - } - Rfft2(const Rfft2 &) = delete; - Rfft2 &operator=(const Rfft2 &) = delete; - ~Rfft2() { - std::unique_lock lock(FFTWPlannerMutex()); - if (fwd) - fftwf_destroy_plan(fwd); - if (bwd) - fftwf_destroy_plan(bwd); } // Zero-pad `src` (height x width) into the workspace and return its spectrum. @@ -57,7 +33,7 @@ public: for (int64_t y = 0; y < height; y++) std::memcpy(&real[static_cast(y * nx)], &src[static_cast(y * width)], sizeof(float) * static_cast(width)); - fftwf_execute(fwd); + cpu_fft::R2C({static_cast(ny), static_cast(nx)}, {0, 1}, real.data(), spectrum.data()); return spectrum; // copy: the workspace is reused } @@ -68,7 +44,7 @@ public: const float norm = 1.0f / (static_cast(ny) * static_cast(nx)); for (size_t i = 0; i < spectrum.size(); i++) spectrum[i] = u[i] * v[i]; - fftwf_execute(bwd); + cpu_fft::C2R({static_cast(ny), static_cast(nx)}, {0, 1}, spectrum.data(), real.data()); std::vector out(static_cast(out_h * out_w)); for (int64_t y = 0; y < out_h; y++) for (int64_t x = 0; x < out_w; x++) @@ -88,8 +64,6 @@ BeamCenterConvSurfaces2D BeamCenterFFTCPU::PointSurfaces(const std::vector the CPU FFT indexer is always built. +# The CPU FFT indexer is always built (its transforms are pocketfft's, common/CpuFFT). TARGET_SOURCES(JFJochIndexing PRIVATE FFTIndexerCPU.cpp FFTIndexerCPU.h) -TARGET_LINK_LIBRARIES(JFJochIndexing fftw3f) diff --git a/image_analysis/indexing/FFTIndexerCPU.cpp b/image_analysis/indexing/FFTIndexerCPU.cpp index 43f663d17..e596cf44f 100644 --- a/image_analysis/indexing/FFTIndexerCPU.cpp +++ b/image_analysis/indexing/FFTIndexerCPU.cpp @@ -7,10 +7,9 @@ #include #include #include -#include #include -#include "../../common/FFTWPlannerLock.h" +#include "../../common/CpuFFT.h" #include "../../common/ParallelFor.h" static inline double dot_abs(const Coord& a, const Coord& b) { @@ -26,32 +25,9 @@ FFTIndexerCPU::FFTIndexerCPU(const IndexingSettings& settings) // Validate allocations vs. expected sizes if (h_input_fft.size() != input_size) - throw std::runtime_error("FFTWIndexer: input buffer size mismatch"); + throw std::runtime_error("FFTIndexerCPU: input buffer size mismatch"); if (h_output_fft.size() != output_size) - throw std::runtime_error("FFTWIndexer: output buffer size mismatch"); - - const int H = static_cast(histogram_size); - const int out_len = (H / 2) + 1; - - int n[1] = { H }; - - { - std::unique_lock ul(FFTWPlannerMutex()); - plan = fftwf_plan_many_dft_r2c( - 1, n, nDirections, - h_input_fft.data(), nullptr, 1, H, - reinterpret_cast(h_output_fft.data()), nullptr, 1, out_len, - FFTW_ESTIMATE); - } - - if (!plan) - throw std::runtime_error("fftw_plan_many_dft_r2c failed"); -} - - -FFTIndexerCPU::~FFTIndexerCPU() { - std::unique_lock ul(FFTWPlannerMutex()); - fftwf_destroy_plan(plan); + throw std::runtime_error("FFTIndexerCPU: output buffer size mismatch"); } void FFTIndexerCPU::ExecuteFFT(const std::vector &coord, size_t nspots) { @@ -80,8 +56,8 @@ void FFTIndexerCPU::ExecuteFFT(const std::vector &coord, size_t nspots) { } }); - // Plan and execute batched R2C FFT with FFTW - fftwf_execute(plan); + // One real transform per direction, all in one call. + cpu_fft::R2C({static_cast(D), static_cast(H)}, {1}, h_input_fft.data(), h_output_fft.data()); // Post-process: pick the peak past min_length_A by PROMINENCE above a local background. // The projected histogram has a broad low-frequency ENVELOPE (spots cluster near the @@ -106,7 +82,7 @@ void FFTIndexerCPU::ExecuteFFT(const std::vector &coord, size_t nspots) { pref[0] = 0.0; for (int j = 0; j < out_len; ++j) { - mag[j] = std::hypot(spec[j][0], spec[j][1]); + mag[j] = std::hypot(spec[j].real(), spec[j].imag()); pref[j + 1] = pref[j] + mag[j]; } diff --git a/image_analysis/indexing/FFTIndexerCPU.h b/image_analysis/indexing/FFTIndexerCPU.h index a784155c0..43beac286 100644 --- a/image_analysis/indexing/FFTIndexerCPU.h +++ b/image_analysis/indexing/FFTIndexerCPU.h @@ -4,30 +4,25 @@ #pragma once +#include #include -#include #include "FFTIndexer.h" #include "../../common/Coord.h" -// CPU/FFTW-based FFT indexer (drop-in replacement for the CUDA version). +// CPU FFT indexer (drop-in replacement for the CUDA version). class FFTIndexerCPU : public FFTIndexer { - // Host-side buffers for batched FFTW + // Host-side buffers for the batched transform // Input: [nDirections][histogram_size] // Output (R2C): [nDirections][(histogram_size/2)+1] std::vector h_input_fft; - std::vector> h_output_fft; // fftw_complex-compatible layout - - fftwf_plan plan; + std::vector> h_output_fft; void ExecuteFFT(const std::vector &coord, size_t nspots) override; public: explicit FFTIndexerCPU(const IndexingSettings& settings); - FFTIndexerCPU(const FFTIndexerCPU&) = delete; - FFTIndexerCPU& operator=(const FFTIndexerCPU&) = delete; - ~FFTIndexerCPU() override; }; diff --git a/image_analysis/scale_merge/CMakeLists.txt b/image_analysis/scale_merge/CMakeLists.txt index 989cfa3d8..ca6b2ba14 100644 --- a/image_analysis/scale_merge/CMakeLists.txt +++ b/image_analysis/scale_merge/CMakeLists.txt @@ -52,7 +52,7 @@ ADD_LIBRARY(JFJochScaleMerge SublatticeRelabel.h IceRingVerdict.cpp IceRingVerdict.h) -TARGET_LINK_LIBRARIES(JFJochScaleMerge Ceres::ceres Eigen3::Eigen JFJochCommon JFJochBraggIntegration fftw3f) +TARGET_LINK_LIBRARIES(JFJochScaleMerge Ceres::ceres Eigen3::Eigen JFJochCommon JFJochBraggIntegration) IF (JFJOCH_CUDA_AVAILABLE) TARGET_SOURCES(JFJochScaleMerge PRIVATE ../indexing/CUDAMemHelpers.h diff --git a/image_analysis/scale_merge/TranslationalNCS.cpp b/image_analysis/scale_merge/TranslationalNCS.cpp index 2acb83aee..cf9e1f486 100644 --- a/image_analysis/scale_merge/TranslationalNCS.cpp +++ b/image_analysis/scale_merge/TranslationalNCS.cpp @@ -5,6 +5,7 @@ #include #include +#include #include #include #include @@ -15,9 +16,7 @@ #include #include -#include - -#include "../../common/FFTWPlannerLock.h" +#include "../../common/CpuFFT.h" #include "../../common/ParallelFor.h" #include "gemmi/twin.hpp" @@ -350,20 +349,15 @@ TranslationalNCSResult AnalyzeTranslationalNCS(const std::vector> coeff; + std::vector map; + try { + coeff.resize(n_complex); + map.resize(n_points); + } catch (const std::bad_alloc &) { result.refusal = "could not allocate the Patterson grid"; return result; } - fftwf_plan plan; - { - std::lock_guard lock(FFTWPlannerMutex()); - plan = fftwf_plan_dft_c2r_3d(nx, ny, nz, reinterpret_cast(coeff), map, - FFTW_ESTIMATE); - } // The near-origin exclusion, as a set of grid points rather than a per-point distance test: only // the points inside a 15 A ball around each origin-equivalent point can be excluded, and there @@ -405,17 +399,15 @@ TranslationalNCSResult AnalyzeTranslationalNCS(const std::vector &values) { - std::memset(coeff, 0, 2 * n_complex * sizeof(float)); + std::fill(coeff.begin(), coeff.end(), std::complex(0.0f, 0.0f)); for (const auto &[at, src] : fill) - coeff[2 * at] += static_cast(values[src]); - fftwf_execute(plan); + coeff[at] += static_cast(values[src]); + cpu_fft::C2R({static_cast(nx), static_cast(ny), static_cast(nz)}, {0, 1, 2}, + coeff.data(), map.data()); }; auto max_far = [&]() { double best = -std::numeric_limits::infinity(); @@ -510,12 +502,6 @@ TranslationalNCSResult AnalyzeTranslationalNCS(const std::vector #include #include -#include -#include - -#include +#include #include "gemmi/fail.hpp" -#include "../../common/FFTWPlannerLock.h" +#include "../../common/CpuFFT.h" #include "../../common/ParallelFor.h" -namespace { +// An (nu, nv, nw) map is stored u fastest - row-major (nw, nv, nu) - and its half-l coefficients +// likewise as (nw/2 + 1, nv, nu): the layout gemmi's own transforms read and write. The real transform +// halves w, so w is the last axis transformed. +static const cpu_fft::Shape kUVW{2, 1, 0}; -// The r2c plan (or, inverse, the c2r plan) for an (nu, nv, nw) map stored u fastest, halving w - the -// layout gemmi's own transforms read and write. FFTW's planner is not thread-safe, so plans are made -// under the process-wide planner lock (which also guards this cache); executing one on new arrays -// (fftwf_execute_dft_r2c / _c2r) is, which is how every caller uses it. -fftwf_plan PlanFor(int nu, int nv, int nw, bool inverse) { - static std::map, fftwf_plan> plans; - std::lock_guard lock(FFTWPlannerMutex()); - const std::array key{nu, nv, nw, inverse}; - if (const auto it = plans.find(key); it != plans.end()) - return it->second; - float *real = fftwf_alloc_real(static_cast(nu) * nv * nw); - fftwf_complex *cplx = fftwf_alloc_complex(static_cast(nu) * nv * (nw / 2 + 1)); - // The last dimension is the one r2c halves; the strides put u fastest on both sides. - fftwf_iodim dims[3] = {{nu, 1, 1}, {nv, nu, nu}, {nw, nu * nv, nu * nv}}; - fftwf_plan plan = nullptr; - if (real != nullptr && cplx != nullptr) - plan = inverse ? fftwf_plan_guru_dft_c2r(3, dims, 0, nullptr, cplx, real, FFTW_ESTIMATE) - : fftwf_plan_guru_dft_r2c(3, dims, 0, nullptr, real, cplx, FFTW_ESTIMATE); - fftwf_free(real); - fftwf_free(cplx); - if (plan == nullptr) - gemmi::fail("ModelFFT: no FFTW plan for the grid"); - plans.emplace(key, plan); - return plan; +static cpu_fft::Shape MapShape(int nu, int nv, int nw) { + return {static_cast(nw), static_cast(nv), static_cast(nu)}; } -} // namespace - gemmi::FPhiGrid MapToFPhi(const gemmi::Grid &map) { if (map.axis_order == gemmi::AxisOrder::ZYX) gemmi::fail("MapToFPhi(): ZYX order is not supported"); @@ -58,30 +34,16 @@ gemmi::FPhiGrid MapToFPhi(const gemmi::Grid &map) { hkl.set_size_without_checking(map.nu, map.nv, map.nw / 2 + 1); const float norm = static_cast(map.unit_cell.volume / map.point_count()); - const fftwf_plan plan = PlanFor(map.nu, map.nv, map.nw, false); - // Buffers from fftwf_malloc: a plan may only be executed on arrays aligned as the ones it was made - // on were, which the vectors' own allocations do not promise. - float *in = fftwf_alloc_real(map.data.size()); - fftwf_complex *out = fftwf_alloc_complex(hkl.data.size()); - if (in == nullptr || out == nullptr) { - fftwf_free(in); - fftwf_free(out); - gemmi::fail("MapToFPhi(): cannot allocate the FFT buffers"); - } - std::copy(map.data.begin(), map.data.end(), in); - fftwf_execute_dft_r2c(plan, in, out); - // Conjugated, as gemmi does: FFTW's forward transform carries exp(-2 pi i h.x), and a structure + cpu_fft::R2C(MapShape(map.nu, map.nv, map.nw), kUVW, map.data.data(), hkl.data.data()); + // Conjugated, as gemmi does: the forward transform carries exp(-2 pi i h.x), and a structure // factor is the sum over exp(+2 pi i h.x). - for (size_t i = 0; i < hkl.data.size(); ++i) - hkl.data[i] = std::complex(out[i][0] * norm, -out[i][1] * norm); - fftwf_free(in); - fftwf_free(out); + for (auto &x : hkl.data) + x = std::conj(x) * norm; return hkl; } void MapFromFPhiExecute(int nu, int nv, int nw, std::complex *in, float *out) { - static_assert(sizeof(std::complex) == sizeof(fftwf_complex)); - fftwf_execute_dft_c2r(PlanFor(nu, nv, nw, true), reinterpret_cast(in), out); + cpu_fft::C2R(MapShape(nu, nv, nw), kUVW, in, out); } gemmi::FPhiGrid MapToFPhiInParallel(const gemmi::Grid &map, int reach, size_t nthreads) { @@ -89,34 +51,12 @@ gemmi::FPhiGrid MapToFPhiInParallel(const gemmi::Grid &map, int re gemmi::fail("MapToFPhiInParallel(): ZYX order is not supported"); const int nu = map.nu, nv = map.nv, nw = map.nw, nwh = nw / 2 + 1, nk = 2 * reach + 1; const size_t plane = static_cast(nu) * nv; - float *in = fftwf_alloc_real(map.data.size()); - fftwf_complex *half = fftwf_alloc_complex(plane * nwh); - if (in == nullptr || half == nullptr) { - fftwf_free(in); - fftwf_free(half); - gemmi::fail("MapToFPhiInParallel(): cannot allocate the FFT buffers"); - } - // Made once here; executing a plan on new arrays is safe from several threads at once. Unaligned, as a - // column or a plane starts wherever it does. - fftwf_plan columns = nullptr, planes = nullptr; - { - std::lock_guard lock(FFTWPlannerMutex()); - // The nu columns of one v, w along the stride of a plane. - fftwf_iodim col_dim{nw, static_cast(plane), static_cast(plane)}; - fftwf_iodim col_many{nu, 1, 1}; - columns = fftwf_plan_guru_dft_r2c(1, &col_dim, 1, &col_many, in, half, FFTW_ESTIMATE | FFTW_UNALIGNED); - fftwf_iodim plane_dims[2] = {{nv, nu, nu}, {nu, 1, 1}}; - planes = fftwf_plan_guru_dft(2, plane_dims, 0, nullptr, half, half, FFTW_FORWARD, FFTW_ESTIMATE | FFTW_UNALIGNED); - } - if (columns == nullptr || planes == nullptr) - gemmi::fail("MapToFPhiInParallel(): no FFTW plan for the grid"); - std::copy(map.data.begin(), map.data.end(), in); - ParallelFor(nv, nthreads, [&](int v) { - fftwf_execute_dft_r2c(columns, in + static_cast(v) * nu, half + static_cast(v) * nu); - }); - ParallelFor(reach + 1, nthreads, [&](int l) { - fftwf_execute_dft(planes, half + l * plane, half + l * plane); - }); + std::vector> half(plane * nwh); + // The r2c along w of every (u, v) column, then the 2D transform of the planes l <= reach only - the + // rest are never read. Each is one call split over the threads by lines. + cpu_fft::R2C({static_cast(nw), plane}, {0}, map.data.data(), half.data(), nthreads); + cpu_fft::C2C({static_cast(reach) + 1, static_cast(nv), static_cast(nu)}, {1, 2}, true, + half.data(), nthreads); gemmi::FPhiGrid hkl; hkl.unit_cell = map.unit_cell; @@ -128,19 +68,12 @@ gemmi::FPhiGrid MapToFPhiInParallel(const gemmi::Grid &map, int re // Conjugated and scaled as MapToFPhi does it, and cropped as CropHalfL crops it. ParallelFor(reach + 1, nthreads, [&](int l) { for (int k = -reach; k <= reach; k++) { - const fftwf_complex *row = half + l * plane + static_cast(nu) * gemmi::modulo(k, nv); + const std::complex *row = &half[l * plane + static_cast(nu) * gemmi::modulo(k, nv)]; std::complex *out = &hkl.data[static_cast(nu) * (gemmi::modulo(k, nk) + static_cast(nk) * l)]; for (int u = 0; u < nu; u++) - out[u] = std::complex(row[u][0] * norm, -row[u][1] * norm); + out[u] = std::conj(row[u]) * norm; } }); - { - std::lock_guard lock(FFTWPlannerMutex()); - fftwf_destroy_plan(columns); - fftwf_destroy_plan(planes); - } - fftwf_free(in); - fftwf_free(half); return hkl; } @@ -154,26 +87,14 @@ gemmi::Grid MapFromFPhi(const gemmi::FPhiGrid &hkl) { map.axis_order = hkl.axis_order; const float norm = static_cast(1.0 / hkl.unit_cell.volume); - const fftwf_plan plan = PlanFor(map.nu, map.nv, map.nw, true); - fftwf_complex *in = fftwf_alloc_complex(hkl.data.size()); - float *out = fftwf_alloc_real(map.data.size()); - if (in == nullptr || out == nullptr) { - fftwf_free(in); - fftwf_free(out); - gemmi::fail("MapFromFPhi(): cannot allocate the FFT buffers"); - } - // Conjugated, as gemmi does: rho(x) = 1/V sum F exp(-2 pi i h.x), and FFTW's backward transform + // Conjugated, as gemmi does: rho(x) = 1/V sum F exp(-2 pi i h.x), and the backward transform // carries exp(+2 pi i h.x). A missing coefficient (NaN) counts as zero, also as gemmi does. - for (size_t i = 0; i < hkl.data.size(); ++i) { - const std::complex x = hkl.data[i]; - in[i][0] = std::isnan(x.imag()) ? 0.0f : x.real(); - in[i][1] = std::isnan(x.imag()) ? 0.0f : -x.imag(); - } - fftwf_execute_dft_c2r(plan, in, out); - for (size_t i = 0; i < map.data.size(); ++i) - map.data[i] = out[i] * norm; - fftwf_free(in); - fftwf_free(out); + std::vector> in(hkl.data.size()); + for (size_t i = 0; i < in.size(); ++i) + in[i] = std::isnan(hkl.data[i].imag()) ? 0.0f : std::conj(hkl.data[i]); + cpu_fft::C2R(MapShape(map.nu, map.nv, map.nw), kUVW, in.data(), map.data.data()); + for (auto &x : map.data) + x *= norm; return map; } diff --git a/image_analysis/structure_refinement/ModelFFT.h b/image_analysis/structure_refinement/ModelFFT.h index d59d64984..1e44a294a 100644 --- a/image_analysis/structure_refinement/ModelFFT.h +++ b/image_analysis/structure_refinement/ModelFFT.h @@ -9,30 +9,23 @@ // The structure factors of a real-space map on the model path (Fcalc from the model density, Fmask // from the bulk-solvent mask): what gemmi::transform_map_to_f_phi(map, true) returns - the // conjugated forward transform (F = sum rho exp(+2 pi i h.x)) scaled by V/N, kept for l >= 0 on an (nu, nv, nw/2+1) grid in the map's own XYZ order, -// ready for prepare_asu_data() - computed with FFTW rather than gemmi's single-threaded pocketfft. -// The same transform, not the same bits: the two libraries order their arithmetic differently. -// -// Plans are FFTW_ESTIMATE only - MEASURE would time candidate algorithms and could pick a different -// one from run to run - and made once per grid size and kept, so the rigid body's hundred-odd -// evaluations on one grid plan once. Safe to call from several threads at once. +// ready for prepare_asu_data() - computed with common/CpuFFT. Safe to call from several threads at once. gemmi::FPhiGrid MapToFPhi(const gemmi::Grid &map); // The inverse: the real-space map of an (nu, nv, nw/2+1) half-l coefficient grid in XYZ order, as // get_f_phi_on_grid() fills it - what gemmi::transform_f_phi_grid_to_map() returns (rho = 1/V sum F -// exp(-2 pi i h.x) on an (nu, nv, 2*(nw-1)) grid, NaN coefficients read as zero), computed with FFTW -// under the same planning rules. +// exp(-2 pi i h.x) on an (nu, nv, 2*(nw-1)) grid, NaN coefficients read as zero). gemmi::Grid MapFromFPhi(const gemmi::FPhiGrid &hkl); // MapFromFPhi's transform itself, for a caller that fills its input: `in`, the (nu, nv, nw/2+1) half-l coefficients -// u fastest as MapFromFPhi hands them to FFTW (conjugated, a NaN as zero), is overwritten, and `out` receives the -// (nu, nv, nw) map before MapFromFPhi's 1/V. Both from fftwf_malloc, as a plan requires. +// u fastest as MapFromFPhi transforms them (conjugated, a NaN as zero), is overwritten, and `out` receives the +// (nu, nv, nw) map before MapFromFPhi's 1/V. void MapFromFPhiExecute(int nu, int nv, int nw, std::complex *in, float *out); // CropHalfL(MapToFPhi(map), reach) on `nthreads` threads, for a map of hundreds of millions of points (the // molecular transform's box), whose single-threaded transform is minutes of CPU: the r2c along w of every -// (u, v) column, then the 2D transform of every plane l <= reach - each column and each plane by one plan, so -// the result does not depend on the thread count. The same transform as MapToFPhi to float rounding, not bit -// for bit: FFTW's 3D plan orders its arithmetic its own way. +// (u, v) column, then the 2D transform of every plane l <= reach. The threads split the lines of a transform, each +// line transformed as it would be alone, so the result does not depend on the thread count. gemmi::FPhiGrid MapToFPhiInParallel(const gemmi::Grid &map, int reach, size_t nthreads); // The half-l grid `full` with only the indices |k|, l <= reach kept, on a grid of full.nu x (2 reach + 1) x diff --git a/image_analysis/structure_refinement/MolecularReplacement.cpp b/image_analysis/structure_refinement/MolecularReplacement.cpp index 6abacdba9..0afb637e9 100644 --- a/image_analysis/structure_refinement/MolecularReplacement.cpp +++ b/image_analysis/structure_refinement/MolecularReplacement.cpp @@ -19,7 +19,6 @@ #include #include -#include #include // remove_hydrogens, remove_alternative_conformations #include // setup_entities, remove_ligands_and_waters @@ -1602,13 +1601,8 @@ TranslationPeak translation_function(const MolecularTransform &ft, const Transla w[t] = setup.weight[t] / (bin_sum[setup.bin[t]] / bin_n[setup.bin[t]]); const int nu = setup.nu, nv = setup.nv, nw = setup.nw; const size_t cells = static_cast(nu) * nv * (nw / 2 + 1), points = static_cast(nu) * nv * nw; - auto *in = reinterpret_cast *>(fftwf_alloc_complex(cells)); - float *map = fftwf_alloc_real(points); - if (in == nullptr || map == nullptr) { - fftwf_free(in); - fftwf_free(map); - throw std::runtime_error("TranslationFunction: cannot allocate the FFT buffers"); - } + std::vector> in(cells); + std::vector map(points); for (size_t c = 0; c < cells; c++) { std::complex v = 0.0; for (int k = gather.offset[c]; k < gather.offset[c + 1]; k++) { @@ -1626,7 +1620,7 @@ TranslationPeak translation_function(const MolecularTransform &ft, const Transla const std::complex f(std::conj(v)); in[c] = std::isnan(f.imag()) ? std::complex(0.0f, 0.0f) : std::complex(f.real(), -f.imag()); } - MapFromFPhiExecute(nu, nv, nw, in, map); + MapFromFPhiExecute(nu, nv, nw, in.data(), map.data()); const float norm = static_cast(1.0 / ft.Grid().unit_cell.volume); double sum = 0, sum2 = 0; size_t best = 0; @@ -1640,8 +1634,6 @@ TranslationPeak translation_function(const MolecularTransform &ft, const Transla const double count = static_cast(points); const double mean = sum / count, sd = std::sqrt(std::max(0.0, sum2 / count - mean * mean)); out.z = sd > 0 ? (map[best] * norm - mean) / sd : 0.0; - fftwf_free(in); - fftwf_free(map); const size_t u = best % nu, v = (best / nu) % nv, l = best / (static_cast(nu) * nv); out.t = gemmi::Fractional(static_cast(u) / nu, static_cast(v) / nv, static_cast(l) / nw); return out; diff --git a/image_analysis/structure_refinement/RefinementXray.cpp b/image_analysis/structure_refinement/RefinementXray.cpp index 7f8991888..955e887d3 100644 --- a/image_analysis/structure_refinement/RefinementXray.cpp +++ b/image_analysis/structure_refinement/RefinementXray.cpp @@ -10,7 +10,6 @@ #include #include -#include #include "gemmi/dencalc.hpp" #include "gemmi/it92.hpp" @@ -188,9 +187,8 @@ public: // l = nw/2, which hold both, as both. const int nu = grid_.nu, nv = grid_.nv, nw = grid_.nw, nwh = nw / 2 + 1; const size_t ncomplex = static_cast(nu) * nv * nwh; - std::complex *in = reinterpret_cast *>(fftwf_alloc_complex(ncomplex)); - float *out = fftwf_alloc_real(static_cast(nu) * nv * nw); - std::fill(in, in + ncomplex, std::complex(0, 0)); + std::vector> in(ncomplex); + std::vector out(static_cast(nu) * nv * nw); const std::vector &terms = composition_.Terms(); const size_t ops = composition_.Ops(); auto add = [&](int ku, int kv, int kw, std::complex value) { @@ -217,13 +215,11 @@ public: } } } - MapFromFPhiExecute(nu, nv, nw, in, out); + MapFromFPhiExecute(nu, nv, nw, in.data(), out.data()); gemmi::Grid map = grid_; const float norm = static_cast(cell_.volume / static_cast(map.point_count())); for (size_t i = 0; i < map.data.size(); i++) map.data[i] = out[i] * norm; - fftwf_free(in); - fftwf_free(out); const bool aniso = AnyAniso(); AtomGradientsFromMap(map, model, blur_, nthreads_, *grad, aniso ? &grad_u_ : nullptr); if (!aniso) diff --git a/rugnux/CMakeLists.txt b/rugnux/CMakeLists.txt index 55379b405..12db3d061 100644 --- a/rugnux/CMakeLists.txt +++ b/rugnux/CMakeLists.txt @@ -41,7 +41,7 @@ ADD_LIBRARY(JFJochRugnux STATIC BrokerFeed.h ) -TARGET_LINK_LIBRARIES(JFJochRugnux JFJochReader JFJochImageAnalysis JFJochPreview gemmi fftw3f +TARGET_LINK_LIBRARIES(JFJochRugnux JFJochReader JFJochImageAnalysis JFJochPreview gemmi httplib::httplib) # The files of a run, written by the programs that run one (rugnux, the viewer) from what JFJochRugnux diff --git a/rugnux/rugnux_cli.cpp b/rugnux/rugnux_cli.cpp index 3238a24fd..4f1ebe1f7 100644 --- a/rugnux/rugnux_cli.cpp +++ b/rugnux/rugnux_cli.cpp @@ -846,21 +846,6 @@ namespace { } } -// FFTW ends the program itself when its allocator comes back empty (CK(p) in kernel/alloc.c) - while -// planning, or inside a buffered transform - from whichever thread that happens in, so it cannot become -// an exception. Defining its handler here keeps FFTW's own (kernel/assert.c) out of the link, and says -// what happened in the same words as every other way of running out of memory. -extern "C" void fftwf_assertion_failed(const char *s, int line, const char *file) { - std::fflush(stdout); - if (std::strcmp(s, "p") == 0) { - std::fprintf(stderr, "Processing failed: out of host memory (FFTW could not allocate) - " - "this data set needs more RAM than is available\n"); - std::_Exit(EXIT_FAILURE); - } - std::fprintf(stderr, "fftw: %s:%d: assertion failed: %s\n", file, line, s); - std::abort(); -} - namespace { // One input's run ended: what exit(EXIT_FAILURE) was where a command line ran one input only. A run of // several sweeps goes on with the next sweep; RunRugnux returns the code. diff --git a/tests/BeamCenterFFTGPUTest.cpp b/tests/BeamCenterFFTGPUTest.cpp index 3f5d1618b..d30023a78 100644 --- a/tests/BeamCenterFFTGPUTest.cpp +++ b/tests/BeamCenterFFTGPUTest.cpp @@ -174,10 +174,11 @@ TEST_CASE("BeamCenterFFTGPU_MatchesTheCPUEngine", "[BeamCenter][BeamCenterFFTGPU std::abs(static_cast(rg[i]) - rc[i])); CHECK(peak_worst < 1e-5); // And the gate agrees: over four million centres, the two paths disagree about whether a - // centre is scored at all only for a handful sitting exactly on the threshold. + // centre is scored at all only for a handful sitting exactly on the threshold (measured: 7 + // with FFTW on the CPU, 17 with pocketfft, whose float error is FFTW's or lower). const auto diff = Compare(rg, rc, &c.D, 0.26f * d_max); CHECK(diff.gate_mismatches == 0); - CHECK(Compare(rg, rc).gate_mismatches < 10); + CHECK(Compare(rg, rc).gate_mismatches < 30); // The device kernel against that reference, on the device's own surfaces - so this measures // the combination and not the transform. diff --git a/tests/CMakeLists.txt b/tests/CMakeLists.txt index b316d427c..17b290a3e 100644 --- a/tests/CMakeLists.txt +++ b/tests/CMakeLists.txt @@ -237,6 +237,7 @@ ADD_EXECUTABLE(jfjoch_test LatticeReductionTest.cpp BeamCenterFromBackgroundTest.cpp BeamCenterFFTTest.cpp + CpuFFTTest.cpp BeamCenterFFTGPUTest.cpp BearerTokensTest.cpp BrokerHttpAuthTest.cpp @@ -246,7 +247,7 @@ ADD_EXECUTABLE(jfjoch_test target_link_libraries(jfjoch_test Catch2WithMain JFJochBroker JFJochReceiver JFJochReader JFJochStreamWriter JFJochRugnuxOutput JFJochRugnux JFJochModelWriter JFJochImageAnalysis JFJochCommon JFJochHLSSimulation JFJochPreview - jfjoch_xds_plugin ZLIB::ZLIB httplib::httplib) + jfjoch_xds_plugin ZLIB::ZLIB httplib::httplib fftw3f) target_include_directories(jfjoch_test PRIVATE .) IF (JFJOCH_CUDA_AVAILABLE) TARGET_COMPILE_DEFINITIONS(jfjoch_test PRIVATE FFBIDX_SIMPLE_DATA_DIR="${FFBIDX_SIMPLE_DATA_DIR}") diff --git a/tests/CpuFFTTest.cpp b/tests/CpuFFTTest.cpp new file mode 100644 index 000000000..2046231d6 --- /dev/null +++ b/tests/CpuFFTTest.cpp @@ -0,0 +1,117 @@ +// SPDX-FileCopyrightText: 2026 Filip Leonarski, Paul Scherrer Institute +// SPDX-License-Identifier: GPL-3.0-only + +#include + +#include +#include +#include +#include + +#include + +#include "../common/CpuFFT.h" +#include "../image_analysis/structure_refinement/ModelFFT.h" + +// pocketfft (common/CpuFFT) against FFTW on the shapes and layouts the call sites use: the same +// transform to float rounding. FFTW is linked into the test binary only, as the reference. + +namespace { + +std::vector Random(size_t n, unsigned seed) { + std::mt19937 rng(seed); + std::normal_distribution g(0.0f, 1.0f); + std::vector v(n); + for (auto &x : v) + x = g(rng); + return v; +} + +// Largest difference relative to the largest value of the reference. +template +double RelativeError(const std::vector &a, const std::vector &ref) { + REQUIRE(a.size() == ref.size()); + double diff = 0, scale = 0; + for (size_t i = 0; i < a.size(); i++) { + diff = std::max(diff, static_cast(std::abs(a[i] - ref[i]))); + scale = std::max(scale, static_cast(std::abs(ref[i]))); + } + return diff / scale; +} + +} // namespace + +TEST_CASE("CpuFFT_BatchedR2CMatchesFFTW", "[fft]") { + // The FFT indexer's histograms: one transform per direction; 3142 = 2 x 1571 is a real length. + for (int n : {3142, 3150, 1024}) { + const int howmany = 37, nc = n / 2 + 1; + std::vector in = Random(static_cast(howmany) * n, n); + std::vector> ours(static_cast(howmany) * nc), ref(ours.size()); + cpu_fft::R2C({static_cast(howmany), static_cast(n)}, {1}, in.data(), ours.data()); + std::vector work = in; + fftwf_plan p = fftwf_plan_many_dft_r2c(1, &n, howmany, work.data(), nullptr, 1, n, + reinterpret_cast(ref.data()), nullptr, 1, nc, + FFTW_ESTIMATE); + fftwf_execute(p); + fftwf_destroy_plan(p); + CHECK(RelativeError(ours, ref) < 1e-5); + } +} + +TEST_CASE("CpuFFT_2DRoundTripMatchesFFTW", "[fft]") { + // The beam-centre search: a 2D r2c and c2r on a 2-3-5-7-smooth padded size. + const int ny = 210, nx = 336, nxc = nx / 2 + 1; + std::vector in = Random(static_cast(ny) * nx, 1); + std::vector> ours(static_cast(ny) * nxc), ref(ours.size()); + cpu_fft::R2C({static_cast(ny), static_cast(nx)}, {0, 1}, in.data(), ours.data()); + std::vector work = in; + fftwf_plan p = fftwf_plan_dft_r2c_2d(ny, nx, work.data(), reinterpret_cast(ref.data()), + FFTW_ESTIMATE); + fftwf_execute(p); + fftwf_destroy_plan(p); + CHECK(RelativeError(ours, ref) < 1e-5); + + std::vector back_ours(in.size()), back_ref(in.size()); + cpu_fft::C2R({static_cast(ny), static_cast(nx)}, {0, 1}, ours.data(), back_ours.data()); + p = fftwf_plan_dft_c2r_2d(ny, nx, reinterpret_cast(ref.data()), back_ref.data(), FFTW_ESTIMATE); + fftwf_execute(p); + fftwf_destroy_plan(p); + CHECK(RelativeError(back_ours, back_ref) < 1e-5); +} + +TEST_CASE("CpuFFT_3DMatchesFFTW", "[fft]") { + // The model maps (u fastest, w halved) and the tNCS Patterson (row-major, last axis halved) are both a + // row-major 3D transform halving the last axis; an odd length and a factor 7 included. + const int n0 = 70, n1 = 45, n2 = 54, nc = static_cast(static_cast(n0) * n1 * (n2 / 2 + 1)); + const std::vector in = Random(static_cast(n0) * n1 * n2, 2); + std::vector> ours(nc), ref(nc); + cpu_fft::R2C({70, 45, 54}, {0, 1, 2}, in.data(), ours.data()); + std::vector work = in; + fftwf_plan p = fftwf_plan_dft_r2c_3d(n0, n1, n2, work.data(), reinterpret_cast(ref.data()), + FFTW_ESTIMATE); + fftwf_execute(p); + fftwf_destroy_plan(p); + CHECK(RelativeError(ours, ref) < 1e-5); + + std::vector back_ours(in.size()), back_ref(in.size()); + cpu_fft::C2R({70, 45, 54}, {0, 1, 2}, ours.data(), back_ours.data()); + p = fftwf_plan_dft_c2r_3d(n0, n1, n2, reinterpret_cast(ref.data()), back_ref.data(), + FFTW_ESTIMATE); + fftwf_execute(p); + fftwf_destroy_plan(p); + CHECK(RelativeError(back_ours, back_ref) < 1e-5); +} + +TEST_CASE("CpuFFT_MapToFPhiInParallelMatchesMapToFPhi", "[fft]") { + gemmi::Grid map; + map.unit_cell.set(60, 50, 40, 90, 90, 90); + map.spacegroup = gemmi::find_spacegroup_by_name("P1"); + map.set_size(60, 50, 40); + map.data = Random(map.data.size(), 3); + const int reach = 12; + const gemmi::FPhiGrid ref = CropHalfL(MapToFPhi(map), reach); + for (size_t nthreads : {1, 4}) { + const gemmi::FPhiGrid ours = MapToFPhiInParallel(map, reach, nthreads); + CHECK(RelativeError(ours.data, ref.data) < 1e-5); + } +} diff --git a/viewer/CMakeLists.txt b/viewer/CMakeLists.txt index 2251557d6..0345b7587 100644 --- a/viewer/CMakeLists.txt +++ b/viewer/CMakeLists.txt @@ -124,7 +124,7 @@ ADD_EXECUTABLE(jfjoch_viewer jfjoch_viewer.cpp JFJochViewerWindow.cpp JFJochView TARGET_LINK_LIBRARIES(jfjoch_viewer Qt6::Core Qt6::Gui Qt6::Widgets Qt6::Charts Qt6::Concurrent JFJochReader JFJochLogger JFJochCommon JFJochWriter JFJochImageAnalysis JFJochRugnux JFJochRugnuxOutput - fftw3f httplib::httplib MbedTLS::mbedtls) + httplib::httplib MbedTLS::mbedtls) # HTTPS for the live-broker client. Defined here, on the viewer only, not on httplib::httplib: the # broker shares that target and stays plain HTTP. JFJochHttpReader.cpp is the one viewer source diff --git a/viewer/charts/JFJochDatasetInfoChartView.cpp b/viewer/charts/JFJochDatasetInfoChartView.cpp index 5a3dc3c44..03b8ce9fb 100644 --- a/viewer/charts/JFJochDatasetInfoChartView.cpp +++ b/viewer/charts/JFJochDatasetInfoChartView.cpp @@ -13,7 +13,7 @@ #include #include "JFJochDatasetInfoChartView.h" -#include "../../common/FFTWPlannerLock.h" +#include "../../common/CpuFFT.h" namespace { // Qt Charts draws its curves 2 px wide, which is hard to follow across a desk. Take the weight @@ -1122,25 +1122,7 @@ void JFJochDatasetInfoChartView::buildFFTChart() { std::vector> out(static_cast(nComplex)); - fftwf_plan plan; - { - std::lock_guard lock(FFTWPlannerMutex()); - plan = fftwf_plan_dft_r2c_1d( - n, - in.data(), - reinterpret_cast(out.data()), - FFTW_ESTIMATE); - } - - if (!plan) { - return; - } - - fftwf_execute(plan); - { - std::lock_guard lock(FFTWPlannerMutex()); - fftwf_destroy_plan(plan); - } + cpu_fft::R2C({N}, {0}, in.data(), out.data()); // Compute amplitude spectrum and frequencies (0 .. Nyquist) m_fftMagnitudes.resize(static_cast(nComplex)); diff --git a/viewer/charts/JFJochDatasetInfoChartView.h b/viewer/charts/JFJochDatasetInfoChartView.h index 5c1c82794..e6c1cfb40 100644 --- a/viewer/charts/JFJochDatasetInfoChartView.h +++ b/viewer/charts/JFJochDatasetInfoChartView.h @@ -15,10 +15,6 @@ #include #include -#ifdef JFJOCH_USE_FFTW -#include -#endif - #include "../../common/GoniometerAxis.h" #include "../../reader/JFJochReaderDataset.h" -- 2.54.1 From 9705845de7ac0794115d760e384720ca6beaa94d Mon Sep 17 00:00:00 2001 From: Filip Leonarski Date: Sun, 15 Nov 2026 23:40:13 +0100 Subject: [PATCH 087/229] Refinement CPU gradient: gather the box's points, then vectorisable loops AtomGradientsFromMap() walked each atom's box and summed the Gaussians of every point in one scalar loop (float -> double conversions, an integer modulo per point, a push of nine accumulators per Gaussian for an anisotropic atom), which perf showed as 81% of a CPU refinement. The walk now gathers the points within the radius (map value, place, r^2; the u index wrapped by a counter), the Gaussians' terms are worked out a Gaussian at a time in loops the compiler vectorises (the exponent in a loop of its own, as the two together do not vectorise), and the derivatives are then summed over the points in the walk's order, the Gaussians of each in turn - the same terms in the same order, so the gradient is bit for bit the one before. Microbenchmark (144^3 grid, 2658 atoms, 2442 of them anisotropic, one thread): 0.415 s -> 0.128 s per gradient. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01UqXYdJDrM65gxsCn2PrbfK --- .../structure_refinement/RefinementXray.cpp | 215 +++++++++++------- 1 file changed, 137 insertions(+), 78 deletions(-) diff --git a/image_analysis/structure_refinement/RefinementXray.cpp b/image_analysis/structure_refinement/RefinementXray.cpp index 955e887d3..595771ede 100644 --- a/image_analysis/structure_refinement/RefinementXray.cpp +++ b/image_analysis/structure_refinement/RefinementXray.cpp @@ -761,35 +761,32 @@ std::unique_ptr MakeRefinementEngineCPU(const gemmi::UnitCell namespace { -// AtomGradientsFromMap() for an anisotropic atom, gridded as PutModelDensityOnGrid() grids it: rho = occ sum_q a_q -// exp(r^T M_q r), M_q = -4 pi^2 (B_q I + 8 pi^2 U + blur I)^-1 and r = centre - point. Then d rho / d(centre) = -// occ sum_q 2 e_q M_q r, and, as d a_q / dU = -4 pi^2 a_q (B..)^-1 = a_q M_q and d(r^T M_q r) / dU = 2 (M_q r)(M_q r)^T, -// d rho / dU = occ sum_q e_q (M_q + 2 (M_q r)(M_q r)^T) - an off-diagonal U_ij twice its matrix element. -void AnisoGradient(const gemmi::Grid &map, const gemmi::DensityCalculator &dc, - const gemmi::Atom &atom, double blur, std::array &grad, std::array *grad_u) { - using CReal = Table::Coef::coef_type; - const auto &coef = IonFormFactor(atom.element.elem, atom.charge); - const auto aniso_b = atom.aniso.scaled(CReal(gemmi::u_to_b())).added_kI(CReal(blur)); - const CReal b_max = AnisoRadiusB(aniso_b); - const double radius = dc.estimate_radius(coef.precalculate_density_iso(b_max, 0.0f), b_max); - const auto precal = coef.precalculate_density_aniso_b(aniso_b, 0.0f); - const float max_r2 = static_cast(radius * radius); +// The points of one atom's box (about the grid point c, c - d to c + d along each axis) within max_r2 of its centre +// nctr (in grid units), in the order of the walk: the map's value there and the place relative to the atom (the +// centre minus the point, orthogonal, and its square) - gathered for the loops over the points that follow, which the +// compiler vectorises, with the scratch they use. +struct MapPoints { + size_t n = 0; // the first n of each + std::vector value, x, y, z, r2, exponent; + std::vector s0, s1, terms; +}; + +void GatherMapPoints(const gemmi::Grid &map, const float nctr[3], const int c[3], const int d[3], float max_r2, + MapPoints &p) { const int nu = map.nu, nv = map.nv, nw = map.nw; + // As ModelGrid.cpp walks a density box: the orthogonalization over the grid size in single precision. const gemmi::UpperTriangularMat33 &om = map.orth_n; const float m00 = static_cast(om.a11), m01 = static_cast(om.a12), m02 = static_cast(om.a13), m11 = static_cast(om.a22), m12 = static_cast(om.a23), m22 = static_cast(om.a33); - const gemmi::Fractional fpos = map.unit_cell.fractionalize(atom.pos); - const double n3[3] = {fpos.x * nu, fpos.y * nv, fpos.z * nw}; - float nctr[3]; - int c[3], d[3]; - for (int k = 0; k < 3; k++) { - nctr[k] = static_cast(n3[k]); - c[k] = gemmi::iround(n3[k]); + const size_t box = static_cast(2 * d[0] + 1) * (2 * d[1] + 1) * (2 * d[2] + 1); + if (p.value.size() < box) { + p.value.resize(box); + p.x.resize(box); + p.y.resize(box); + p.z.resize(box); + p.r2.resize(box); } - d[0] = std::min(static_cast(std::ceil(radius / map.spacing[0])), nu - 1); - d[1] = std::min(static_cast(std::ceil(radius / map.spacing[1])), nv - 1); - d[2] = std::min(static_cast(std::ceil(radius / map.spacing[2])), nw - 1); - double g[3] = {0, 0, 0}, gu[6] = {0, 0, 0, 0, 0, 0}; + size_t n = 0; for (int w = c[2] - d[2]; w <= c[2] + d[2]; w++) { const float fz = nctr[2] - static_cast(w); const float z = m22 * fz; @@ -801,30 +798,101 @@ void AnisoGradient(const gemmi::Grid &map, const gemmi::DensityCalculator if (yz > max_r2) continue; const float x_yz = m01 * fy + m02 * fz; - const size_t row = static_cast(nu) * (gemmi::modulo(v, nv) + static_cast(nv) * w_); - for (int u = c[0] - d[0]; u <= c[0] + d[0]; u++) { + const float *row = &map.data[static_cast(nu) * (gemmi::modulo(v, nv) + static_cast(nv) * w_)]; + for (int u = c[0] - d[0], u_ = gemmi::modulo(u, nu); u <= c[0] + d[0]; u++, u_ = (u_ + 1 == nu ? 0 : u_ + 1)) { const float x = m00 * (nctr[0] - static_cast(u)) + x_yz; - if (yz + x * x > max_r2) + const float r2 = yz + x * x; + if (r2 > max_r2) continue; - const double value = map.data[row + gemmi::modulo(u, nu)]; - for (size_t q = 0; q < std::size(precal.a); q++) { - const gemmi::SMat33 &m = precal.b[q]; - const gemmi::Vec3f r(x, y, z); - const double e = value * precal.a[q] * gemmi::unsafe_expapprox(std::max(m.r_u_r(r), -88.f)); - const double mr[3] = {m.u11 * x + m.u12 * y + m.u13 * z, m.u12 * x + m.u22 * y + m.u23 * z, - m.u13 * x + m.u23 * y + m.u33 * z}; - for (int k = 0; k < 3; k++) - g[k] += e * mr[k]; - gu[0] += e * (m.u11 + 2 * mr[0] * mr[0]); - gu[1] += e * (m.u22 + 2 * mr[1] * mr[1]); - gu[2] += e * (m.u33 + 2 * mr[2] * mr[2]); - gu[3] += e * (m.u12 + 2 * mr[0] * mr[1]); - gu[4] += e * (m.u13 + 2 * mr[0] * mr[2]); - gu[5] += e * (m.u23 + 2 * mr[1] * mr[2]); - } + p.value[n] = row[u_]; + p.x[n] = x; + p.y[n] = y; + p.z[n] = z; + p.r2[n] = r2; + n++; } } } + p.n = n; +} + +// AtomGradientsFromMap() for an anisotropic atom, gridded as PutModelDensityOnGrid() grids it: rho = occ sum_q a_q +// exp(r^T M_q r), M_q = -4 pi^2 (B_q I + 8 pi^2 U + blur I)^-1 and r = centre - point. Then d rho / d(centre) = +// occ sum_q 2 e_q M_q r, and, as d a_q / dU = -4 pi^2 a_q (B..)^-1 = a_q M_q and d(r^T M_q r) / dU = 2 (M_q r)(M_q r)^T, +// d rho / dU = occ sum_q e_q (M_q + 2 (M_q r)(M_q r)^T) - an off-diagonal U_ij twice its matrix element. +void AnisoGradient(const gemmi::Grid &map, const gemmi::DensityCalculator &dc, + const gemmi::Atom &atom, double blur, MapPoints &p, std::array &grad, + std::array *grad_u) { + using CReal = Table::Coef::coef_type; + const auto &coef = IonFormFactor(atom.element.elem, atom.charge); + const auto aniso_b = atom.aniso.scaled(CReal(gemmi::u_to_b())).added_kI(CReal(blur)); + const CReal b_max = AnisoRadiusB(aniso_b); + const double radius = dc.estimate_radius(coef.precalculate_density_iso(b_max, 0.0f), b_max); + const auto precal = coef.precalculate_density_aniso_b(aniso_b, 0.0f); + const float max_r2 = static_cast(radius * radius); + const int nu = map.nu, nv = map.nv, nw = map.nw; + const gemmi::Fractional fpos = map.unit_cell.fractionalize(atom.pos); + const double n3[3] = {fpos.x * nu, fpos.y * nv, fpos.z * nw}; + float nctr[3]; + int c[3], d[3]; + for (int k = 0; k < 3; k++) { + nctr[k] = static_cast(n3[k]); + c[k] = gemmi::iround(n3[k]); + } + d[0] = std::min(static_cast(std::ceil(radius / map.spacing[0])), nu - 1); + d[1] = std::min(static_cast(std::ceil(radius / map.spacing[1])), nv - 1); + d[2] = std::min(static_cast(std::ceil(radius / map.spacing[2])), nw - 1); + GatherMapPoints(map, nctr, c, d, max_r2, p); + const size_t np = p.n, nq = std::size(precal.a); + // In blocks of points: per Gaussian q and point k the nine terms the derivatives sum, e (M_q r)_t and + // e (M_q + 2 (M_q r)(M_q r)^T)_tt' with e = value a_q exp(r^T M_q r), at (t nq + q) BLOCK + k, then summed over the + // points in the walk's order, the Gaussians of each in turn. + constexpr size_t BLOCK = 64; + p.terms.resize(9 * nq * BLOCK); + double g[3] = {0, 0, 0}, gu[6] = {0, 0, 0, 0, 0, 0}; + for (size_t k0 = 0; k0 < np; k0 += BLOCK) { + const size_t nb = std::min(BLOCK, np - k0); + const float *x = &p.x[k0], *y = &p.y[k0], *z = &p.z[k0], *value = &p.value[k0]; + for (size_t q = 0; q < nq; q++) { + const gemmi::SMat33 &m = precal.b[q]; + const float a = precal.a[q]; + float exponent[BLOCK]; + for (size_t k = 0; k < nb; k++) + exponent[k] = std::max(m.r_u_r(gemmi::Vec3f(x[k], y[k], z[k])), -88.f); + double *t[9]; + for (int c = 0; c < 9; c++) + t[c] = &p.terms[(c * nq + q) * BLOCK]; + for (size_t k = 0; k < nb; k++) { + const double e = static_cast(value[k]) * a * gemmi::unsafe_expapprox(exponent[k]); + const double mr0 = m.u11 * x[k] + m.u12 * y[k] + m.u13 * z[k]; + const double mr1 = m.u12 * x[k] + m.u22 * y[k] + m.u23 * z[k]; + const double mr2 = m.u13 * x[k] + m.u23 * y[k] + m.u33 * z[k]; + t[0][k] = e * mr0; + t[1][k] = e * mr1; + t[2][k] = e * mr2; + t[3][k] = e * (m.u11 + 2 * mr0 * mr0); + t[4][k] = e * (m.u22 + 2 * mr1 * mr1); + t[5][k] = e * (m.u33 + 2 * mr2 * mr2); + t[6][k] = e * (m.u12 + 2 * mr0 * mr1); + t[7][k] = e * (m.u13 + 2 * mr0 * mr2); + t[8][k] = e * (m.u23 + 2 * mr1 * mr2); + } + } + for (size_t k = 0; k < nb; k++) + for (size_t q = 0; q < nq; q++) { + const double *t = &p.terms[q * BLOCK + k]; + const size_t c = nq * BLOCK; // from one term to the next + g[0] += t[0]; + g[1] += t[c]; + g[2] += t[2 * c]; + gu[0] += t[3 * c]; + gu[1] += t[4 * c]; + gu[2] += t[5 * c]; + gu[3] += t[6 * c]; + gu[4] += t[7 * c]; + gu[5] += t[8 * c]; + } + } const double occ = atom.occ; grad = {2 * occ * g[0], 2 * occ * g[1], 2 * occ * g[2], occ * (gu[0] + gu[1] + gu[2]) / gemmi::u_to_b()}; if (grad_u != nullptr) @@ -845,16 +913,13 @@ void AtomGradientsFromMap(const gemmi::Grid &map, const gemmi::Model &mod if (grad_u != nullptr) grad_u->assign(atoms.size(), {0, 0, 0, 0, 0, 0}); const int nu = map.nu, nv = map.nv, nw = map.nw; - // As ModelGrid.cpp walks a density box: the orthogonalization over the grid size in single precision. - const gemmi::UpperTriangularMat33 &om = map.orth_n; - const float m00 = static_cast(om.a11), m01 = static_cast(om.a12), m02 = static_cast(om.a13), - m11 = static_cast(om.a22), m12 = static_cast(om.a23), m22 = static_cast(om.a33); constexpr double FOUR_PI2 = 4 * refine_math::PI * refine_math::PI; ParallelChunks(static_cast(atoms.size()), nthreads, [&](int lo, int hi) { + MapPoints p; for (int i = lo; i < hi; i++) { const gemmi::Atom &atom = *atoms[i]; if (atom.aniso.nonzero()) { - AnisoGradient(map, dc, atom, blur, grad[i], grad_u != nullptr ? &(*grad_u)[i] : nullptr); + AnisoGradient(map, dc, atom, blur, p, grad[i], grad_u != nullptr ? &(*grad_u)[i] : nullptr); continue; } const float b = static_cast(atom.b_iso + blur); @@ -872,38 +937,32 @@ void AtomGradientsFromMap(const gemmi::Grid &map, const gemmi::Model &mod d[0] = std::min(static_cast(std::ceil(radius / map.spacing[0])), nu - 1); d[1] = std::min(static_cast(std::ceil(radius / map.spacing[1])), nv - 1); d[2] = std::min(static_cast(std::ceil(radius / map.spacing[2])), nw - 1); - double gx = 0, gy = 0, gz = 0, gb = 0; - for (int w = c[2] - d[2]; w <= c[2] + d[2]; w++) { - const float fz = nctr[2] - static_cast(w); - const float z = m22 * fz; - const int w_ = gemmi::modulo(w, nw); - for (int v = c[1] - d[1]; v <= c[1] + d[1]; v++) { - const float fy = nctr[1] - static_cast(v); - const float y = m11 * fy + m12 * fz; - const float yz = y * y + z * z; - if (yz > max_r2) - continue; - const float x_yz = m01 * fy + m02 * fz; - const size_t row = static_cast(nu) * (gemmi::modulo(v, nv) + static_cast(nv) * w_); - for (int u = c[0] - d[0]; u <= c[0] + d[0]; u++) { - const float x = m00 * (nctr[0] - static_cast(u)) + x_yz; - const float r2 = yz + x * x; - if (r2 > max_r2) - continue; - const double value = map.data[row + gemmi::modulo(u, nu)]; - double dr2 = 0, db = 0; - for (size_t q = 0; q < std::size(precal.a); q++) { - const double e = precal.a[q] * gemmi::unsafe_expapprox(std::max(precal.b[q] * r2, -88.f)); - dr2 += e * precal.b[q]; - db += e * precal.b[q] * (1.5 + precal.b[q] * r2); - } - gx += value * dr2 * x; - gy += value * dr2 * y; - gz += value * dr2 * z; - gb += value * db; - } + GatherMapPoints(map, nctr, c, d, max_r2, p); + const size_t np = p.n; + // the two sums over the Gaussians per point, a Gaussian at a time, each point still summing them in order + // from 0 (as AtomDensity does); the exponent in a loop of its own, as the two together do not vectorise + std::vector &sum_dr2 = p.s0, &sum_db = p.s1; + sum_dr2.assign(np, 0.0); + sum_db.assign(np, 0.0); + p.exponent.resize(np); + for (size_t q = 0; q < std::size(precal.a); q++) { + const float a = precal.a[q], bq = precal.b[q]; + for (size_t k = 0; k < np; k++) + p.exponent[k] = std::max(bq * p.r2[k], -88.f); + for (size_t k = 0; k < np; k++) { + const double e = a * gemmi::unsafe_expapprox(p.exponent[k]); + sum_dr2[k] += e * bq; + sum_db[k] += e * bq * (1.5 + bq * p.r2[k]); } } + double gx = 0, gy = 0, gz = 0, gb = 0; + for (size_t k = 0; k < np; k++) { + const double v = p.value[k]; + gx += v * sum_dr2[k] * p.x[k]; + gy += v * sum_dr2[k] * p.y[k]; + gz += v * sum_dr2[k] * p.z[k]; + gb += v * sum_db[k]; + } // rho = occ sum_q a_q exp(b_q r^2): d rho / d(centre) = occ 2 (sum a_q b_q e_q) (centre - point), and // with b_q = -4 pi^2 / (B_q + B + blur), d rho / dB = occ sum a_q e_q b_q (1.5 + b_q r^2) / (4 pi^2). grad[i] = {2.0 * atom.occ * gx, 2.0 * atom.occ * gy, 2.0 * atom.occ * gz, atom.occ * gb / FOUR_PI2}; -- 2.54.1 From 491e950e12d16776fd6ae18d8868de8301b53141 Mon Sep 17 00:00:00 2001 From: Filip Leonarski Date: Sun, 15 Nov 2026 23:49:52 +0100 Subject: [PATCH 088/229] Refinement on the CPU: the engine and the mask take the slot's share of the threads The CPU engine and the bulk-solvent mask kept the thread count they were made with: the main slot's all of them, every other weight-trial slot's one (settings.nthreads / slots). RunTrials and the stages that hand the threads back set Context::nthreads, which the engine never read - so where fewer trials ran than there were slots (the trajectory's steps run 4, TLS/U hypotheses, the last trial of a set) the trials in the other slots ran on one thread each and the step waited for them; top showed the process at 100-500% for most of a run on 16 threads. Context::SetThreads() now passes the count on (RefinementEngine::SetThreads, a no-op on a GPU engine, and BulkSolventMask::SetThreads), and the engine's and the mask's FFTs are split over the same threads (MapToFPhi/MapFromFPhiExecute take nthreads; pocketfft splits lines, the result is the same). The outcome does not depend on the threads: cytC --mode refine --no-gpu -N 16 writes the same refined model and maps bit for bit, R-free 0.3400 / 0.3366 (two hypotheses) as before. Refinement time, with the gradient commit before it: 909.6 + 700.7 s -> 224.7 + 219.7 s (wall 1611 -> 445 s). Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01UqXYdJDrM65gxsCn2PrbfK --- .../structure_refinement/ModelFFT.cpp | 8 ++++---- image_analysis/structure_refinement/ModelFFT.h | 7 ++++--- .../structure_refinement/Refinement.cpp | 18 ++++++++++++------ .../structure_refinement/RefinementXray.cpp | 9 +++++---- .../structure_refinement/RefinementXray.h | 3 +++ 5 files changed, 28 insertions(+), 17 deletions(-) diff --git a/image_analysis/structure_refinement/ModelFFT.cpp b/image_analysis/structure_refinement/ModelFFT.cpp index 8d2dc41ca..66318286d 100644 --- a/image_analysis/structure_refinement/ModelFFT.cpp +++ b/image_analysis/structure_refinement/ModelFFT.cpp @@ -23,7 +23,7 @@ static cpu_fft::Shape MapShape(int nu, int nv, int nw) { return {static_cast(nw), static_cast(nv), static_cast(nu)}; } -gemmi::FPhiGrid MapToFPhi(const gemmi::Grid &map) { +gemmi::FPhiGrid MapToFPhi(const gemmi::Grid &map, size_t nthreads) { if (map.axis_order == gemmi::AxisOrder::ZYX) gemmi::fail("MapToFPhi(): ZYX order is not supported"); gemmi::FPhiGrid hkl; @@ -34,7 +34,7 @@ gemmi::FPhiGrid MapToFPhi(const gemmi::Grid &map) { hkl.set_size_without_checking(map.nu, map.nv, map.nw / 2 + 1); const float norm = static_cast(map.unit_cell.volume / map.point_count()); - cpu_fft::R2C(MapShape(map.nu, map.nv, map.nw), kUVW, map.data.data(), hkl.data.data()); + cpu_fft::R2C(MapShape(map.nu, map.nv, map.nw), kUVW, map.data.data(), hkl.data.data(), nthreads); // Conjugated, as gemmi does: the forward transform carries exp(-2 pi i h.x), and a structure // factor is the sum over exp(+2 pi i h.x). for (auto &x : hkl.data) @@ -42,8 +42,8 @@ gemmi::FPhiGrid MapToFPhi(const gemmi::Grid &map) { return hkl; } -void MapFromFPhiExecute(int nu, int nv, int nw, std::complex *in, float *out) { - cpu_fft::C2R(MapShape(nu, nv, nw), kUVW, in, out); +void MapFromFPhiExecute(int nu, int nv, int nw, std::complex *in, float *out, size_t nthreads) { + cpu_fft::C2R(MapShape(nu, nv, nw), kUVW, in, out, nthreads); } gemmi::FPhiGrid MapToFPhiInParallel(const gemmi::Grid &map, int reach, size_t nthreads) { diff --git a/image_analysis/structure_refinement/ModelFFT.h b/image_analysis/structure_refinement/ModelFFT.h index 1e44a294a..d5dae7501 100644 --- a/image_analysis/structure_refinement/ModelFFT.h +++ b/image_analysis/structure_refinement/ModelFFT.h @@ -9,8 +9,9 @@ // The structure factors of a real-space map on the model path (Fcalc from the model density, Fmask // from the bulk-solvent mask): what gemmi::transform_map_to_f_phi(map, true) returns - the // conjugated forward transform (F = sum rho exp(+2 pi i h.x)) scaled by V/N, kept for l >= 0 on an (nu, nv, nw/2+1) grid in the map's own XYZ order, -// ready for prepare_asu_data() - computed with common/CpuFFT. Safe to call from several threads at once. -gemmi::FPhiGrid MapToFPhi(const gemmi::Grid &map); +// ready for prepare_asu_data() - computed with common/CpuFFT, its lines split over `nthreads` (the same result on any +// number). Safe to call from several threads at once. +gemmi::FPhiGrid MapToFPhi(const gemmi::Grid &map, size_t nthreads = 1); // The inverse: the real-space map of an (nu, nv, nw/2+1) half-l coefficient grid in XYZ order, as // get_f_phi_on_grid() fills it - what gemmi::transform_f_phi_grid_to_map() returns (rho = 1/V sum F @@ -20,7 +21,7 @@ gemmi::Grid MapFromFPhi(const gemmi::FPhiGrid &hkl); // MapFromFPhi's transform itself, for a caller that fills its input: `in`, the (nu, nv, nw/2+1) half-l coefficients // u fastest as MapFromFPhi transforms them (conjugated, a NaN as zero), is overwritten, and `out` receives the // (nu, nv, nw) map before MapFromFPhi's 1/V. -void MapFromFPhiExecute(int nu, int nv, int nw, std::complex *in, float *out); +void MapFromFPhiExecute(int nu, int nv, int nw, std::complex *in, float *out, size_t nthreads = 1); // CropHalfL(MapToFPhi(map), reach) on `nthreads` threads, for a map of hundreds of millions of points (the // molecular transform's box), whose single-threaded transform is minutes of CPU: the r2c along w of every diff --git a/image_analysis/structure_refinement/Refinement.cpp b/image_analysis/structure_refinement/Refinement.cpp index 89e79549a..6da085ab2 100644 --- a/image_analysis/structure_refinement/Refinement.cpp +++ b/image_analysis/structure_refinement/Refinement.cpp @@ -172,6 +172,12 @@ struct Context { std::shared_ptr scale_gpu; // shared by the slots on the engine's card #endif size_t nthreads = 1; + // The threads of the stages and of the engine and the mask from now on. + void SetThreads(size_t n) { + nthreads = n; + engine->SetThreads(n); + mask->SetThreads(n); + } // the likelihood fit's: all of the run's, also in a trial's slot - the slots refit at the same time, the GPU // idles meanwhile, and the bins they queue on the shared worker pool are fitted by whichever thread is free size_t ml_threads = 1; @@ -1961,7 +1967,7 @@ std::vector RunTrials(const std::vector &trial_slots, // the threads shared among the slots that run (the outcome does not depend on how many each has) const size_t running = std::min(trial_slots.size(), trials.size()); for (size_t s = 0; s < running; s++) - trial_slots[s].ctx->nthreads = std::max(1, settings.nthreads / running); + trial_slots[s].ctx->SetThreads(std::max(1, settings.nthreads / running)); // The longest go to the slots first - TLS bodies, then a U per atom, then the B factors refined, then held - so // that two of them share a card only where the cards are fewer than they are: the slots are on the cards in turn // (OwnSlotPlaces), a card's second slot only after every card's first. @@ -2817,7 +2823,7 @@ RefinementResult RefineOnce(const gemmi::Structure &placed, const std::vector trial_slots{{&ctx, &topo}}; for (const std::unique_ptr &o : own) if (o) @@ -3124,7 +3130,7 @@ RefinementResult RefineOnce(const gemmi::Structure &placed, const std::vector &v) { std::string s; @@ -3828,7 +3834,7 @@ RefinementResult RefineOnce(const gemmi::Structure &placed, const std::vector 0) logger.Debug("Refinement: {} target evaluations in trials run ahead and not needed", ahead_evaluations); - ctx.nthreads = main_threads; + ctx.SetThreads(main_threads); if (state.ran) { ctx.SetPositions(state.pos); ctx.SetB(state.b); diff --git a/image_analysis/structure_refinement/RefinementXray.cpp b/image_analysis/structure_refinement/RefinementXray.cpp index 595771ede..871d53af1 100644 --- a/image_analysis/structure_refinement/RefinementXray.cpp +++ b/image_analysis/structure_refinement/RefinementXray.cpp @@ -115,6 +115,7 @@ public: void SetBlur(double blur) override { blur_ = blur; } void SetRowModel(const XrayRowModel &rows) override { rows_ = rows; } bool OnGPU() const override { return false; } + void SetThreads(size_t nthreads) override { nthreads_ = nthreads; } void Fcalc(const gemmi::Model &model, std::vector> &f) override { std::vector> fd; @@ -125,7 +126,7 @@ public: void Fmask(const gemmi::Model &model, std::vector> &f) override { gemmi::Grid mask = grid_; PutMaskOnGrid(mask, model, orbit_leaders_, nthreads_); - const gemmi::FPhiGrid fm = MapToFPhi(mask); + const gemmi::FPhiGrid fm = MapToFPhi(mask, nthreads_); f.clear(); for (const gemmi::Miller &h : refl_.RowHkl()) f.push_back(fm.get_value_by_hkl(h)); @@ -215,7 +216,7 @@ public: } } } - MapFromFPhiExecute(nu, nv, nw, in.data(), out.data()); + MapFromFPhiExecute(nu, nv, nw, in.data(), out.data(), nthreads_); gemmi::Grid map = grid_; const float norm = static_cast(cell_.volume / static_cast(map.point_count())); for (size_t i = 0; i < map.data.size(); i++) @@ -240,7 +241,7 @@ private: void Compose(const gemmi::Model &model, std::vector> &f) const { gemmi::DensityCalculator dc = Calculator(cell_, sg_, d_min_, blur_); PutModelDensityOnGrid(dc, model, {}, nthreads_, true, true); // one copy: the symmetry is composed below - composition_.Compose(MapToFPhi(dc.grid), blur_, f, nullptr, nthreads_); + composition_.Compose(MapToFPhi(dc.grid, nthreads_), blur_, f, nullptr, nthreads_); } gemmi::UnitCell cell_; @@ -557,7 +558,7 @@ void BulkSolventMask::Fmask(const gemmi::Model &model, const std::vector fm = MapToFPhi(mask); + const gemmi::FPhiGrid fm = MapToFPhi(mask, nthreads_); sub.reset(); f.clear(); for (const gemmi::Miller &h : hkl) diff --git a/image_analysis/structure_refinement/RefinementXray.h b/image_analysis/structure_refinement/RefinementXray.h index 3b8640d6e..66bf1dd44 100644 --- a/image_analysis/structure_refinement/RefinementXray.h +++ b/image_analysis/structure_refinement/RefinementXray.h @@ -121,6 +121,7 @@ public: void Fmask(const gemmi::Model &model, const std::vector &hkl, std::vector> &f) const; double Spacing() const { return spacing_; } + void SetThreads(size_t nthreads) { nthreads_ = nthreads; } private: gemmi::Grid grid_; @@ -205,6 +206,8 @@ public: // For an anisotropic atom (SetAniso) the B derivative is the one along dev + B / (8 pi^2) I, its shape held. virtual double Evaluate(const gemmi::Model &model, std::vector> *grad) = 0; virtual bool OnGPU() const = 0; + // The threads the engine's evaluations are spread over from now on (the CPU's; a GPU engine keeps its own). + virtual void SetThreads(size_t) {} // Which atoms are anisotropic and their shapes, in model order (AtomAniso), read at every Fcalc() and // Evaluate() until it is set again; null or empty: every atom isotropic (the model's own aniso is not read). -- 2.54.1 From b36fcd0892bcfe866631be5e9ce01a1e9eda0dd5 Mon Sep 17 00:00:00 2001 From: Filip Leonarski Date: Mon, 16 Nov 2026 00:58:51 +0100 Subject: [PATCH 089/229] Refinement CPU gradient: atoms in blocks taken as the threads come free AtomGradientsFromMap() gave each thread one contiguous range of atoms; an anisotropic atom or one of high B costs several times another, and the threads of the cheap ranges waited for the rest. The atoms now go in blocks of 16 off a shared counter (ParallelFor), each thread with scratch of its own; every atom's derivatives are the same. Microbenchmark (2658 atoms, 144^3 grid): 16 threads 20.4 -> 17.2 ms, 8 threads 21.8 -> 17.9 ms. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01UqXYdJDrM65gxsCn2PrbfK --- image_analysis/structure_refinement/RefinementXray.cpp | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/image_analysis/structure_refinement/RefinementXray.cpp b/image_analysis/structure_refinement/RefinementXray.cpp index 871d53af1..e718b5d18 100644 --- a/image_analysis/structure_refinement/RefinementXray.cpp +++ b/image_analysis/structure_refinement/RefinementXray.cpp @@ -915,9 +915,13 @@ void AtomGradientsFromMap(const gemmi::Grid &map, const gemmi::Model &mod grad_u->assign(atoms.size(), {0, 0, 0, 0, 0, 0}); const int nu = map.nu, nv = map.nv, nw = map.nw; constexpr double FOUR_PI2 = 4 * refine_math::PI * refine_math::PI; - ParallelChunks(static_cast(atoms.size()), nthreads, [&](int lo, int hi) { - MapPoints p; - for (int i = lo; i < hi; i++) { + // in blocks of atoms taken as the threads come free: an anisotropic atom, or one of high B, costs several times + // another, and one contiguous range per thread left the threads of the cheap ranges waiting + constexpr int ATOM_BLOCK = 16; + const int n = static_cast(atoms.size()); + ParallelFor((n + ATOM_BLOCK - 1) / ATOM_BLOCK, nthreads, [&](int block) { + thread_local MapPoints p; + for (int i = block * ATOM_BLOCK; i < std::min(n, (block + 1) * ATOM_BLOCK); i++) { const gemmi::Atom &atom = *atoms[i]; if (atom.aniso.nonzero()) { AnisoGradient(map, dc, atom, blur, p, grad[i], grad_u != nullptr ? &(*grad_u)[i] : nullptr); -- 2.54.1 From a1ea5499805b9c0a457ab9a61f9e6e8805929c85 Mon Sep 17 00:00:00 2001 From: Filip Leonarski Date: Mon, 16 Nov 2026 00:58:51 +0100 Subject: [PATCH 090/229] Refinement weight trials on the CPU: every thread dealt out, an idle slot's threads passed on RunTrials gave each running slot settings.nthreads / slots threads, rounded down: 12 population members on 16 threads ran on 12, a ladder of 14 trials on 14. And a slot that had no trial left kept its threads idle while the longest trials ran on (a ladder's B-held trials end well before the ones refining B). On the CPU the remainder is now dealt to the first slots, and a slot that has run out of trials adds its threads to a shared count that the slots still running take up at their next target evaluation (Context::TakeSpareThreads). A GPU engine's slots are shared out as before. The outcome does not depend on the threads. cytC --mode refine --no-gpu -N 16: the same refined model bit for bit; refinement 224.7 + 219.7 s -> 190.7 + 186.3 s, wall 445 -> 378 s, the process busy on 13.5 cores on average (was 10.3). Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01UqXYdJDrM65gxsCn2PrbfK --- .../structure_refinement/Refinement.cpp | 29 +++++++++++++++++-- 1 file changed, 26 insertions(+), 3 deletions(-) diff --git a/image_analysis/structure_refinement/Refinement.cpp b/image_analysis/structure_refinement/Refinement.cpp index 6da085ab2..3e1cf4d5c 100644 --- a/image_analysis/structure_refinement/Refinement.cpp +++ b/image_analysis/structure_refinement/Refinement.cpp @@ -178,6 +178,15 @@ struct Context { engine->SetThreads(n); mask->SetThreads(n); } + // Where the trials run side by side on the CPU (RunTrials), the threads of the slots that have no trial left, + // which the slots still running take up at their next evaluation (TakeSpareThreads); null elsewhere. + std::atomic *spare_threads = nullptr; + void TakeSpareThreads() { + if (spare_threads == nullptr) + return; + if (const int n = spare_threads->exchange(0); n > 0) + SetThreads(nthreads + n); + } // the likelihood fit's: all of the run's, also in a trial's slot - the slots refit at the same time, the GPU // idles meanwhile, and the bins they queue on the shared worker pool are fitted by whichever thread is free size_t ml_threads = 1; @@ -746,6 +755,7 @@ public: bool Evaluate(const double *p, double *cost, double *gradient) const { const RefinementStage stage(mode_ == Mode::Xyz ? "eval.xyz" : "eval.b"); + ctx_.TakeSpareThreads(); Set(p); ctx_.evaluations++; std::vector> &gx = gx_, &gr = gr_; @@ -867,6 +877,7 @@ public: bool Evaluate(const double *p, double *cost, double *gradient) const { const RefinementStage stage(mode_ == Mode::U ? "eval.u" : "eval.tls"); + ctx_.TakeSpareThreads(); Set(p); ctx_.evaluations++; std::vector> gx; @@ -1964,10 +1975,17 @@ std::vector RunTrials(const std::vector &trial_slots, bool hold_positions = false) { std::vector out(trials.size()); std::vector errors(trial_slots.size()); - // the threads shared among the slots that run (the outcome does not depend on how many each has) + // The threads shared among the slots that run (the outcome does not depend on how many each has). On the CPU + // every thread is dealt out, and a slot that has no trial left gives its threads to those still running. const size_t running = std::min(trial_slots.size(), trials.size()); - for (size_t s = 0; s < running; s++) - trial_slots[s].ctx->SetThreads(std::max(1, settings.nthreads / running)); + const bool on_cpu = !trial_slots[0].ctx->engine->OnGPU(); + std::atomic spare_threads{0}; + for (size_t s = 0; s < running; s++) { + const size_t share = settings.nthreads / running + (on_cpu && s < settings.nthreads % running ? 1 : 0); + trial_slots[s].ctx->SetThreads(std::max(1, share)); + if (on_cpu) + trial_slots[s].ctx->spare_threads = &spare_threads; + } // The longest go to the slots first - TLS bodies, then a U per atom, then the B factors refined, then held - so // that two of them share a card only where the cards are fewer than they are: the slots are on the cards in turn // (OwnSlotPlaces), a card's second slot only after every card's first. @@ -1991,6 +2009,11 @@ std::vector RunTrials(const std::vector &trial_slots, } catch (...) { errors[s] = std::current_exception(); } + Context &ctx = *trial_slots[s].ctx; + if (ctx.spare_threads != nullptr) { + ctx.spare_threads = nullptr; + spare_threads += static_cast(ctx.nthreads); + } }; std::vector threads; for (size_t s = 1; s < std::min(trial_slots.size(), trials.size()); s++) -- 2.54.1 From 5d61bc3bdb52fadaae20a9d73f25117ec53eb9fd Mon Sep 17 00:00:00 2001 From: Filip Leonarski Date: Mon, 16 Nov 2026 01:18:14 +0100 Subject: [PATCH 091/229] FOR THE OWNER'S DECISION: without a GPU a placed model is not refined unless --refine asks for it On the CPU the refinement is still two orders of magnitude slower than on a GPU (cytC with its reference model, --no-gpu -N 16, after the CPU commits before this one: 378 s against 11 s on an RTX 5080; 1610 s before them), and short of the order of magnitude the owner set as the bar for keeping it on. So a run with no GPU (none, or --no-gpu) now places and scores the model as before and leaves the refinement out, with a log line and a Note saying so, and the report's REFINE= NOT_PERFORMED with REFINE_REASON "no GPU (--refine runs it on the CPU)". --refine (new) runs it on the CPU; --no-refine is unchanged, a GPU run refines as before, and --mode refine (an explicit request) refines on the CPU as before. RugnuxConfig::refine_without_gpu carries it (the viewer, which sets refine, follows the same default). Docs: RUGNUX_CLI.md (--refine, --model), RUGNUX_MODEL_AND_REFERENCE.md. Checked: cytC -e 300 --no-gpu -> REFINE= NOT_PERFORMED with the reason; the same on the GPU -> PERFORMED. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01UqXYdJDrM65gxsCn2PrbfK --- docs/RUGNUX_CLI.md | 3 ++- docs/RUGNUX_MODEL_AND_REFERENCE.md | 3 ++- rugnux/Rugnux.h | 3 +++ rugnux/RugnuxCommandLine.cpp | 2 ++ rugnux/RugnuxScaleMerge.cpp | 12 +++++++++++- rugnux/rugnux_cli.cpp | 9 +++++++++ 6 files changed, 29 insertions(+), 3 deletions(-) diff --git a/docs/RUGNUX_CLI.md b/docs/RUGNUX_CLI.md index de73be06f..47f6ede82 100644 --- a/docs/RUGNUX_CLI.md +++ b/docs/RUGNUX_CLI.md @@ -331,9 +331,10 @@ serial stills; `fft` (GPU) / `fftw` (CPU) index **de novo** and suit strong rota | `-z, --reference ` | Reference data of the same crystal form — an MTZ or a PDB structure-factor mmCIF (`-sf.cif`), gzipped or not, recognised by content; `--reference-mtz` is the same option: fixes the space group, its setting and the cell, resolves the [indexing ambiguity](RUGNUX_ADVANCED.md#the-indexing-ambiguity), hands over the R-free set and reports CCref. Not a scale anchor | | `--free-flags ` | Take only the R-free test set of this MTZ or structure-factor mmCIF - e.g. the deposited reflections of the `--model` - for the validation, the refinement and the merged files; nothing else of the file is used, so unlike `-z` it fixes no space group, cell or frame. Taken on the model's axes where the merge matches the file's intensities (`R_FREE_FLAGS=`, see [Free set and model bias](RUGNUX_MODEL_AND_REFERENCE.md#free-set-and-model-bias)) | | `--reference-column