From 387b31eae0eb76fa3c5f37e40183ece96bb6506b Mon Sep 17 00:00:00 2001 From: Filip Leonarski Date: Sun, 15 Nov 2026 08:44:13 +0100 Subject: [PATCH] -C without -S fixes the crystal system the typed angles name The angles of a cell given with -C (no -S) are read literally and name the crystal system: three 90s orthorhombic (tetragonal or cubic where the lengths are equal within tolerance), two 90s and a 120 hexagonal (or rhombohedral in hexagonal axes), two 90s monoclinic, three equal angles rhombohedral, anything else triclinic (P 1, as before). The system is fixed like a fixed space group fixes the lattice: indexing searches the system's own centrings (LatticeSearchForSystem, one IndexingSettings field), nothing promotes or demotes it (no sub-lattice change, no doubled- cell re-expression, no triclinic adoption), and only the space group within it is searched. Runs without -C, and -S runs, are unchanged. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01UqXYdJDrM65gxsCn2PrbfK --- common/IndexingSettings.cpp | 9 ++++++ common/IndexingSettings.h | 7 +++++ docs/RUGNUX_CLI.md | 2 +- .../lattice_search/LatticeSearch.cpp | 11 +++++++ image_analysis/lattice_search/LatticeSearch.h | 5 ++++ .../rotation_indexer/RotationIndexer.cpp | 9 ++++-- rugnux/Rugnux.cpp | 1 + rugnux/RugnuxFirstPassRescues.cpp | 4 +-- rugnux/RugnuxScaleMerge.cpp | 2 ++ rugnux/rugnux_cli.cpp | 30 ++++++++++++++----- tests/LatticeSearchTest.cpp | 18 +++++++++++ 11 files changed, 86 insertions(+), 12 deletions(-) diff --git a/common/IndexingSettings.cpp b/common/IndexingSettings.cpp index 62f79b8e7..8a4d9fe7e 100644 --- a/common/IndexingSettings.cpp +++ b/common/IndexingSettings.cpp @@ -233,3 +233,12 @@ IndexingSettings &IndexingSettings::MaxExtraLattices(int64_t input) { max_extra_lattices = input; return *this; } + +IndexingSettings &IndexingSettings::FixedLatticeSystem(const std::optional &input) { + fixed_lattice_system = input; + return *this; +} + +const std::optional &IndexingSettings::GetFixedLatticeSystem() const { + return fixed_lattice_system; +} diff --git a/common/IndexingSettings.h b/common/IndexingSettings.h index 6a5e9c508..199959cfc 100644 --- a/common/IndexingSettings.h +++ b/common/IndexingSettings.h @@ -4,6 +4,9 @@ #pragma once #include +#include + +namespace gemmi { enum class CrystalSystem : unsigned char; } // gemmi/symmetry.hpp // Upper bound accepted by IndexingSettings::RefineThreads. Callers deriving a thread count from the // machine must clamp to it - on a big host -N/2 exceeds it and the setter throws. @@ -69,6 +72,7 @@ private: // spot positions place to ~0.1 %, so on a small cell a genuinely orthorhombic crystal is // integrated with a = b imposed and nothing downstream can recover from it. bool lattice_class_demoted = false; + std::optional fixed_lattice_system; bool enable_rotation_indexing = false; @@ -94,6 +98,8 @@ public: IndexingSettings& BlockingBehavior(bool input); IndexingSettings& MaxExtraLattices(int64_t input); IndexingSettings& LatticeClassDemoted(bool input); + // The crystal system a cell given with -C (and no -S) fixes: the lattice is indexed in it, never above or below. + IndexingSettings& FixedLatticeSystem(const std::optional &input); [[nodiscard]] int64_t GetViableCellMinSpots() const; [[nodiscard]] IndexingAlgorithmEnum GetAlgorithm() const; @@ -114,4 +120,5 @@ public: [[nodiscard]] bool GetBlockingBehavior() const; [[nodiscard]] int64_t GetMaxExtraLattices() const; [[nodiscard]] bool GetLatticeClassDemoted() const; + [[nodiscard]] const std::optional &GetFixedLatticeSystem() const; }; diff --git a/docs/RUGNUX_CLI.md b/docs/RUGNUX_CLI.md index 1aebc2588..c07e2e434 100644 --- a/docs/RUGNUX_CLI.md +++ b/docs/RUGNUX_CLI.md @@ -281,7 +281,7 @@ For very long axes the direction grid's angular resolution binds well below 500 | `--force-still` | Treat a rotation (goniometer) dataset as independent stills instead of rotation; several masters are then read as one stills run | | `-X, --indexing-algorithm ` | `Auto` (default) \| `FFT` \| `cuFFT` \| `FFTW` \| `FFBIDX` \| `None`, case-insensitive. `FFT` is the de-novo FFT search, on the GPU (cuFFT) where there is one and `--no-gpu` is not given, otherwise on the CPU (FFTW); `cuFFT` and `FFTW` name one implementation each; `cuFFT` needs a GPU and is refused without one. `FFBIDX` (known cell, `-C`) runs on the GPU where there is one and otherwise on the CPU. `Auto` takes `FFBIDX` on stills with a known cell, and `FFT` otherwise. `FFBIDX` without a cell (`-C`, or one from `-z`) resolves to `None` and indexes nothing, with no error. On rotation data `-X` is not consulted: the FFT search runs on the GPU where there is one and on the CPU otherwise, so `Auto`, `FFT`, `cuFFT` (with a GPU) and `FFTW` (without one, or under `--no-gpu`) are accepted and any other value stops the run at indexing; `FFBIDX` and `None` are for stills | | `-F` | Short for `-X FFT`, kept for old command lines | -| `-C, --unit-cell ` | Reference unit cell `"a,b,c,alpha,beta,gamma"` (required by `ffbidx`). On rotation data it also widens the FFT search to cover the cell given, at both ends: the longest axis looked for is raised to reach it, and `--fft-min-unit-cell` is lowered to admit it. A candidate that is an integer supercell of the cell given (a twin's coincidence lattice, a row taken at a multiple of its length) is stepped down to it. On stills the run always uses it: the geometry refinement takes it as a prior (1 % on the lengths, 1° on the angles the crystal system leaves free), and the log warns - with both numbers - where the frames refine its shape more than 3 % / 3° away, or where a sample of frames indexed de novo puts materially more spots on the lattice than the cell given ([§7.7](CPU_DATA_ANALYSIS_INDEXING.md#77-stills-a-given-cell-and-the-detector-modules)). Without `-S` the angles are read literally: an angle is 90° or 120° only where it is typed so (`90` or `90.00`, not `90.03`). A cell with no such angle, and not three equal angles, names a triclinic lattice, and the run behaves as with `-S P1` | +| `-C, --unit-cell ` | Reference unit cell `"a,b,c,alpha,beta,gamma"` (required by `ffbidx`). On rotation data it also widens the FFT search to cover the cell given, at both ends: the longest axis looked for is raised to reach it, and `--fft-min-unit-cell` is lowered to admit it. A candidate that is an integer supercell of the cell given (a twin's coincidence lattice, a row taken at a multiple of its length) is stepped down to it. On stills the run always uses it: the geometry refinement takes it as a prior (1 % on the lengths, 1° on the angles the crystal system leaves free), and the log warns - with both numbers - where the frames refine its shape more than 3 % / 3° away, or where a sample of frames indexed de novo puts materially more spots on the lattice than the cell given ([§7.7](CPU_DATA_ANALYSIS_INDEXING.md#77-stills-a-given-cell-and-the-detector-modules)). Without `-S` the cell fixes the crystal system, read from the angles as typed: an angle is 90° or 120° only where it is typed so (`90` or `90.00`, not `90.03`). Three 90s: orthorhombic, or tetragonal / cubic where the lengths are equal within tolerance; two 90s and a 120: hexagonal (or rhombohedral in hexagonal axes); two 90s: monoclinic; three equal angles: rhombohedral; anything else: triclinic, and the run behaves as with `-S P1`. The lattice is indexed in that system, never above or below it, and only the space group within it is searched | | `--fft-min-unit-cell ` | Shortest cell axis the FFT search accepts, Å (default: 10; accepted 5-40). A candidate with a shorter axis is discarded — but on rotation data a row shorter than the floor, down to 3 Å, is recognised under the multiple of it the search reports past the floor, so a small-molecule cell is indexed without this flag. `-C` lowers the floor on its own to cover the cell given. On stills a crystal below the floor cannot be indexed unless this is lowered | | `--min-indexed-spots ` | Spots a frame must have on the lattice before it counts as indexed (default: 6, minimum 4). It sets the reported indexing rate and the count the rotation first pass ranks candidate lattices by; whether the run has a lattice at all is decided on the pooled spots instead ([§4.1](CPU_DATA_ANALYSIS_INDEXING.md#41-indexed-spot-decision-inlier-test)), and integration is not gated by it | | `-S, --space-group ` | Space group number (`96`) or Hermann-Mauguin symbol (`P43212`) — for indexing and scaling. On serial stills whose group admits two indexings, it also lets the crystals be put on one from the data ([the indexing ambiguity](RUGNUX_ADVANCED.md#the-indexing-ambiguity)). A fixed group fixes the lattice: indexing puts the crystal in the group's own Bravais class and nothing promotes, demotes, reduces or doubles it afterwards. A primitive group on a lattice with no primitive cell of its system (P2 on a C-centred monoclinic crystal, P3 on a rhombohedral one) is merged on the centred cell, and the positions the centring extinguishes are kept (they read about zero). With `-C` as well, the cell is written on the given cell's axes | diff --git a/image_analysis/lattice_search/LatticeSearch.cpp b/image_analysis/lattice_search/LatticeSearch.cpp index 505992cdd..ff58afb1e 100644 --- a/image_analysis/lattice_search/LatticeSearch.cpp +++ b/image_analysis/lattice_search/LatticeSearch.cpp @@ -567,6 +567,17 @@ std::optional LatticeSearchForGroup(const CrystalLattice &L return std::nullopt; } +std::optional LatticeSearchForSystem(const CrystalLattice &L, gemmi::CrystalSystem system) { + const bool hexagonal_family = system == gemmi::CrystalSystem::Hexagonal || system == gemmi::CrystalSystem::Trigonal; + for (const char c : {'P', 'C', 'A', 'B', 'I', 'F', 'R'}) { + const auto s = !hexagonal_family ? system + : c == 'R' ? gemmi::CrystalSystem::Trigonal : gemmi::CrystalSystem::Hexagonal; + if (auto r = LatticeSearchForClass(L, s, c)) + return r; + } + return std::nullopt; +} + int LatticePointGroupOrder(gemmi::CrystalSystem system) { switch (system) { case gemmi::CrystalSystem::Monoclinic: return 2; diff --git a/image_analysis/lattice_search/LatticeSearch.h b/image_analysis/lattice_search/LatticeSearch.h index da6ee8451..2c7b85910 100644 --- a/image_analysis/lattice_search/LatticeSearch.h +++ b/image_analysis/lattice_search/LatticeSearch.h @@ -57,6 +57,11 @@ std::optional LatticeSearchForClass(const CrystalLattice& L // metric cannot carry the group's system at all. std::optional LatticeSearchForGroup(const CrystalLattice &L, const gemmi::SpaceGroup &sg); +// The lattice of a crystal system the user fixed (the cell given with -C): the system's centrings are +// tried in turn, primitive first, as the cell typed cannot say which the crystal has and the data can. +// The hexagonal family takes a rhombohedral lattice as well. Empty where the metric carries none. +std::optional LatticeSearchForSystem(const CrystalLattice &L, gemmi::CrystalSystem system); + int LatticePointGroupOrder(gemmi::CrystalSystem system); // Whether the conventional metric of this class asserts an equality between cell LENGTHS (a = b, and diff --git a/image_analysis/rotation_indexer/RotationIndexer.cpp b/image_analysis/rotation_indexer/RotationIndexer.cpp index a2d0a5ec3..03687d73f 100644 --- a/image_analysis/rotation_indexer/RotationIndexer.cpp +++ b/image_analysis/rotation_indexer/RotationIndexer.cpp @@ -155,6 +155,7 @@ namespace { x.GetFFT_MinAngle_deg(), x.GetFFT_MaxAngle_deg(), x.GetUnitCellDistTolerance(), x.GetUnitCellAngleTolerance_deg(), static_cast(x.GetIndexIceRings()), static_cast(x.GetMaxExtraLattices()), static_cast(x.GetLatticeClassDemoted()), + x.GetFixedLatticeSystem() ? 1.0 + static_cast(*x.GetFixedLatticeSystem()) : 0.0, static_cast(x.GetViableCellMinSpots()), static_cast(x.GetAlgorithm()), static_cast(x.GetGeomRefinementAlgorithm()), static_cast(x.GetIndexingThreads()), static_cast(x.GetRefineThreads())}); @@ -319,9 +320,13 @@ void RotationIndexer::RunIndexingLocked() { // have, a metrically hexagonal cell - fires. Only where the metric cannot carry the group's // class does the metric decide, and the scaling then reports the conflict. const bool demote_class = experiment.GetIndexingSettings().GetLatticeClassDemoted(); + // A cell given with -C fixes the crystal system the same way (LatticeSearchForSystem). const auto &fixed_sg = experiment.GetGemmiSpaceGroup(); + const auto &fixed_system = experiment.GetIndexingSettings().GetFixedLatticeSystem(); + const bool lattice_fixed = fixed_sg || fixed_system; auto build_sr = [&](const CrystalLattice &cand) -> LatticeSearchResult { - const auto fixed = fixed_sg ? LatticeSearchForGroup(cand, *fixed_sg) : std::nullopt; + const auto fixed = fixed_sg ? LatticeSearchForGroup(cand, *fixed_sg) + : fixed_system ? LatticeSearchForSystem(cand, *fixed_system) : std::nullopt; auto ls = fixed ? *fixed : LatticeSearch(cand); // The other hypothesis about a promotion that rests on a = b: walk the characters again // granting NO length equality at all, and take the class the metric carries on its angles @@ -418,7 +423,7 @@ void RotationIndexer::RunIndexingLocked() { // Pseudo-symmetry guard: also refine unconstrained (triclinic) on the primitive cell, which // catches a false metric promotion. With a space group the user fixed there is no // promotion to catch - the class is the group's - and no other lattice may be adopted. - w.has_tri = !fixed_sg && w.sr.system != gemmi::CrystalSystem::Triclinic; + w.has_tri = !lattice_fixed && w.sr.system != gemmi::CrystalSystem::Triclinic; if (w.has_tri) w.tri = make_data(w.sr.primitive_reduced, gemmi::CrystalSystem::Triclinic, length_bound_A); w.viable = true; diff --git a/rugnux/Rugnux.cpp b/rugnux/Rugnux.cpp index 48fb8ed89..9a43c9272 100644 --- a/rugnux/Rugnux.cpp +++ b/rugnux/Rugnux.cpp @@ -790,6 +790,7 @@ std::vector Rugnux::ExperimentKey(const DiffractionExperiment &e, bool r x.GetFFT_MinAngle_deg(), x.GetFFT_MaxAngle_deg(), x.GetUnitCellDistTolerance(), x.GetUnitCellAngleTolerance_deg(), static_cast(x.GetIndexIceRings()), static_cast(x.GetMaxExtraLattices()), static_cast(x.GetLatticeClassDemoted()), + x.GetFixedLatticeSystem() ? 1.0 + static_cast(*x.GetFixedLatticeSystem()) : 0.0, static_cast(x.GetViableCellMinSpots()), static_cast(x.GetAlgorithm()), static_cast(x.GetGeomRefinementAlgorithm())}); const auto &f = config_.spot_finding; diff --git a/rugnux/RugnuxFirstPassRescues.cpp b/rugnux/RugnuxFirstPassRescues.cpp index 8b403339a..ce07efff3 100644 --- a/rugnux/RugnuxFirstPassRescues.cpp +++ b/rugnux/RugnuxFirstPassRescues.cpp @@ -961,8 +961,8 @@ namespace { } auto Rugnux::FirstPassRun::SubLatticeHypothesis(FirstPass best) -> FirstPass { - // A space group the user fixed fixes the lattice, its volume included. - if (rx.user_fixed_sg_) + // A space group or a cell the user fixed fixes the lattice, its volume included. + if (rx.user_fixed_sg_ || rx.experiment_.GetIndexingSettings().GetFixedLatticeSystem()) return best; // Asked again of each sub-lattice it adopts: a cell doubled along two or three axes is a sub-lattice // of index 4 or 8, reached one halving at a time. Each cell on the way is first asked whether it is diff --git a/rugnux/RugnuxScaleMerge.cpp b/rugnux/RugnuxScaleMerge.cpp index 290f2a458..96a3b7d7d 100644 --- a/rugnux/RugnuxScaleMerge.cpp +++ b/rugnux/RugnuxScaleMerge.cpp @@ -3176,7 +3176,9 @@ bool Rugnux::ScaleMergeAndSymmetry(PipelineLocals &p) { const bool triclinic_on_centred = sg_search.best_space_group.has_value() && sg_search.best_space_group->crystal_system() == gemmi::CrystalSystem::Triclinic && indexed_centring != 'P'; + // A cell given with -C fixes the lattice, so the cell is never re-expressed on another one. if (!commit_reindex && sg_search.best_space_group.has_value() + && !experiment_.GetIndexingSettings().GetFixedLatticeSystem() && (sg_search.best_space_group->number > 1 || triclinic_on_centred) && end_msg.rotation_lattice.has_value() && end_msg.rotation_lattice_type.has_value()) { const gemmi::SpaceGroup won = *sg_search.best_space_group; diff --git a/rugnux/rugnux_cli.cpp b/rugnux/rugnux_cli.cpp index 13f4fd01c..f5fc3c92e 100644 --- a/rugnux/rugnux_cli.cpp +++ b/rugnux/rugnux_cli.cpp @@ -65,6 +65,7 @@ #include "../image_analysis/UpdateReflectionResolution.h" #include "../image_analysis/WriteReflections.h" #include "../image_analysis/scale_merge/CrystalSetting.h" // CellInBasis, HklOperator +#include "../image_analysis/lattice_search/LatticeSearch.h" #include "../image_analysis/scale_merge/Merge.h" #include "../image_analysis/scale_merge/RfreeFlags.h" #include "../image_analysis/scale_merge/ReindexAmbiguity.h" // MatchReference @@ -938,6 +939,7 @@ struct RugnuxCli { bool anomalous_mode = false; const gemmi::SpaceGroup *space_group = nullptr; std::optional fixed_reference_unit_cell; + std::optional fixed_lattice_system; // from a -C cell without -S std::optional max_spot_count_override; float sigma_spot_finding = SpotFindingSettings{}.signal_to_noise_threshold; int64_t photon_count_threshold_spot_finding = SpotFindingSettings{}.photon_count_threshold; @@ -1996,16 +1998,29 @@ int RugnuxInputRun::PrepareRugnuxInput() { console->Rule('-'); // A cell given with -C and no -S is read literally: an angle is 90 or 120 deg only where it was - // typed so. A cell with no such angle, and not the three equal angles of a rhombohedral cell, names - // a triclinic lattice, so its group is P 1 - and the lattice and setting are then kept as for -S P1. + // typed so, and the angles as typed fix the crystal system - the lattice is then indexed in it, + // never above or below, and only the space group within it is searched. Three 90s: orthorhombic, + // or tetragonal / cubic where the lengths are equal within the usual tolerance; two 90s and a + // 120: hexagonal; two 90s: monoclinic; three equal angles: rhombohedral; anything else names a + // triclinic lattice, whose group is P 1 - and the run then goes as with -S P1. if (fixed_reference_unit_cell && space_group == nullptr) { const auto &c = *fixed_reference_unit_cell; - const auto special = [](double x) { return x == 90.0 || x == 120.0; }; - if (!special(c.alpha) && !special(c.beta) && !special(c.gamma) - && !(c.alpha == c.beta && c.beta == c.gamma)) { + const int n90 = (c.alpha == 90.0f) + (c.beta == 90.0f) + (c.gamma == 90.0f); + const bool has120 = c.alpha == 120.0f || c.beta == 120.0f || c.gamma == 120.0f; + if (n90 == 3) { + const auto s = LatticeSearch(CrystalLattice(c)).system; + fixed_lattice_system = (s == gemmi::CrystalSystem::Tetragonal || s == gemmi::CrystalSystem::Cubic) + ? s : gemmi::CrystalSystem::Orthorhombic; + } else if (n90 == 2) + fixed_lattice_system = has120 ? gemmi::CrystalSystem::Hexagonal : gemmi::CrystalSystem::Monoclinic; + else if (c.alpha == c.beta && c.beta == c.gamma) + fixed_lattice_system = gemmi::CrystalSystem::Trigonal; + if (fixed_lattice_system) + logger.Info("The cell given with -C fixes the crystal system: {}", + gemmi::crystal_system_str(*fixed_lattice_system)); + else { space_group = gemmi::find_spacegroup_by_number(1); - logger.Info("The cell given with -C has no angle of 90 or 120 deg, so it names a triclinic " - "lattice: space group P 1"); + logger.Info("The cell given with -C has no angles that make it more than triclinic: space group P 1"); } } if (space_group != nullptr) @@ -3562,6 +3577,7 @@ int RugnuxInputRun::PrepareRugnuxInput() { indexing_settings.RotationIndexing(rotation_indexing); indexing_settings.GeomRefinementAlgorithm(refinement_algorithm); indexing_settings.IndexIceRings(index_ice_rings); + indexing_settings.FixedLatticeSystem(fixed_lattice_system); if (fft_min_unit_cell_A) indexing_settings.FFT_MinUnitCell_A(fft_min_unit_cell_A.value()); experiment.ImportIndexingSettings(indexing_settings); diff --git a/tests/LatticeSearchTest.cpp b/tests/LatticeSearchTest.cpp index 4abfd2052..c58a69785 100644 --- a/tests/LatticeSearchTest.cpp +++ b/tests/LatticeSearchTest.cpp @@ -786,3 +786,21 @@ TEST_CASE("LatticeSearch - a given triclinic cell that is metrically monoclinic CHECK(p2->centering == 'P'); CHECK(std::abs(p2->conventional.CalcVolume()) == Catch::Approx(2.0 * std::abs(given.CalcVolume())).epsilon(1e-3)); } + +TEST_CASE("LatticeSearch - a crystal system fixed by the given cell is neither promoted nor demoted") { + // Primitive monoclinic, beta 90.4: within the character table's tolerance of orthorhombic. + const CrystalLattice near_ortho(UnitCell(40.0, 55.0, 70.0, 90.0, 90.4, 90.0)); + CHECK(LatticeSearch(near_ortho).system == gemmi::CrystalSystem::Orthorhombic); + + // Typed 90/beta/90 fixes monoclinic: not orthorhombic, and not triclinic either. + const auto mono = LatticeSearchForSystem(near_ortho, gemmi::CrystalSystem::Monoclinic); + REQUIRE(mono.has_value()); + CHECK(mono->system == gemmi::CrystalSystem::Monoclinic); + CHECK(mono->centering == 'P'); + + // The centring is the lattice's: a C-centred monoclinic lattice comes back C. + const CrystalLattice c2_prim = CrystalLattice(UnitCell(21.0, 6.3, 9.8, 90.0, 106.0, 90.0)).ToPrimitive('C'); + const auto c2 = LatticeSearchForSystem(c2_prim, gemmi::CrystalSystem::Monoclinic); + REQUIRE(c2.has_value()); + CHECK(c2->centering == 'C'); +}