Build Packages / build:portable:linux-x86_64:nocuda (push) Successful in 16m43s
Build Packages / build:jfjoch:ubuntu2404:nocuda (push) Successful in 28m46s
Build Packages / build:jfjoch:rocky8:cuda-sls9 (push) Successful in 32m5s
Build Packages / build:jfjoch:rocky9:cuda (push) Successful in 39m44s
Build Packages / build:portable:macos-arm64:nocuda (push) Successful in 5m7s
Build Packages / Create release (push) Successful in 8s
Build Packages / Build documentation (push) Successful in 49s
Build Packages / build:portable:linux-x86_64:cuda (push) Successful in 22m30s
Build Packages / build:jfjoch:rocky8:nocuda (push) Successful in 31m54s
Build Packages / build:rugnux:linux-aarch64:cuda (push) Successful in 11m29s
Build Packages / build:portable:windows-x86_64:nocuda (push) Successful in 23m51s
Build Packages / build:jfjoch:ubuntu2204:nocuda (push) Successful in 26m7s
Build Packages / build:jfjoch:ubuntu2204:cuda (push) Successful in 29m38s
Build Packages / build:portable:windows-x86_64:cuda (push) Successful in 28m6s
Build Packages / HDF5 consumer tests (DIALS, XDS) (push) Successful in 29m44s
Build Packages / build:jfjoch:rocky9:nocuda (push) Successful in 33m22s
Build Packages / Generate python client (push) Successful in 47s
Build Packages / build:jfjoch:rocky9:cuda-sls9 (push) Successful in 34m6s
Build Packages / Unit tests (push) Successful in 1h2m47s
Build Packages / build:jfjoch:rocky8:cuda (push) Successful in 35m59s
Build Packages / build:jfjoch:ubuntu2404:cuda (push) Successful in 34m8s
Build Packages / Validation Battery (push) Successful in 38m31s
* Rugnux: Refinement several times faster, one protocol on the CPU and the GPU, parts of it on the Apple GPU; its random draws are the same on every platform. * Rugnux: Refinement follows common practice: the free set decides only the restraint weights and the displacement model (isotropic, TLS or anisotropic, by Hamilton's test), everything else is decided on the working set; lower R-free for placed and predicted models. * Rugnux: Restraint dictionaries via `--restraints` (or among the inputs) and more built-in ligands; a model whose space group is a subgroup of the data's is refined in its own group; reflections plus a model select `--mode refine` on their own. * Rugnux: `-C` fixes the crystal system on the axes as typed; `-S` alone fixes the space group only, the cell is still found and reduced; a space group or cell stored in the input file is ignored, with a line in the log. * Rugnux: More reliable multi-sweep merging; `--mode scale` merges several stills runs as one; `_plot.txt` and the report name each input; a second crystal form is reported for stills given a cell. * jfjoch_broker (experimental): Live Rugnux on FPGA detectors (JUNGFRAU) takes the same path as a DECTRIS stream, rotation and serial alike, model step included, with analysis threads per GPU; frames waiting for the analysis can be viewed; no host stage drops a frame - a source faster than the analysis is held at the card. * jfjoch_broker: Summation of more than 256 frames per image is split between the card and the host (`summation_mode` is then `hybrid`), and live Rugnux runs on such collections; pedestal runs take a receiver of their own. * jfjoch_broker (experimental): `stills_downsample` analyses 1 of every N serial images (chosen by a hash; the first 2000 all; the others written without analysis; reset to 1 by `/initialize`); `max_spot_count` left out means 250 for per-image indexing and up to 1000 for live stills; the live status gives the merge before the model work, the fitted resolution and the anomalous peak height of each unexplained blob. * jfjoch_broker: Without a `pcie` entry the broker runs on a mock of the card instead of the HLS simulation; its spot, ROI and azimuthal results are zero then. * Web frontend: Redesigned Rugnux live page; Vite 8, TypeScript 6, Mol* 5.13 and dependency security updates. * Tools: `jfjoch_fpga_stills_test` measures live stills on the cards with a stored dataset; `jfjoch_fpga_test` loses the HLS-simulation option. * Other: FFTW no longer fetched or linked (the CPU FFT indexer keeps the name `FFTW`); PCIe driver now GPL-2.0-or-later and third-party notices complete; several crash fixes. Reviewed-on: #98 Co-authored-by: Filip Leonarski <filip.leonarski@psi.ch>
158 lines
9.7 KiB
C++
158 lines
9.7 KiB
C++
// SPDX-FileCopyrightText: 2026 Filip Leonarski, Paul Scherrer Institute <filip.leonarski@psi.ch>
|
|
// SPDX-License-Identifier: GPL-3.0-only
|
|
|
|
#pragma once
|
|
|
|
// The side chains of a model as a discrete field, each residue in one of its rotamers (SideChainRotamers.h: the
|
|
// staggered chi angles, the planar ends every 30 degrees), as it was given, or absent (pruned to CB), searched
|
|
// against the refinement's own target in reciprocal space. The structure factors are linear in the atoms: with
|
|
// F_model = F_rest + dF_r(state_r), dF_r the direct-summation structure factors of residue r's side chain in that
|
|
// state, a residue's change of state moves F by dF_new - dF_old, and -ln L over the working reflections - the
|
|
// scale, the solvent and the likelihood's parameters held where the refinement fitted them - is re-evaluated
|
|
// at every reflection in one pass, a few microseconds on the GPU. The energy of the field is that -ln L plus the
|
|
// repulsion term of the refinement's geometry (the overlaps with the rest of the model, symmetry mates and the other
|
|
// copies included) at the refinement's own X-ray weight. The field is minimised by iterated conditional modes: the
|
|
// residues in turn, each put in the state of least energy given the others, small residues first and arginine last
|
|
// (the order PDB-REDO rebuilds in: Joosten et al. (2011) Bioinformatics 27, 3392-3398), until a sweep changes
|
|
// nothing. The free reflections are never seen: the caller refines from the field and judges on them.
|
|
// Side chains as a discrete field and ICM: following Desmet et al. (1992) Nature 356, 539-542 and
|
|
// Besag (1986) J. R. Statist. Soc. B48, 259-279.
|
|
|
|
#include <array>
|
|
#include <complex>
|
|
#include <memory>
|
|
#include <string>
|
|
#include <vector>
|
|
|
|
#include <gemmi/model.hpp>
|
|
#include <gemmi/symmetry.hpp>
|
|
#include <gemmi/unitcell.hpp>
|
|
|
|
#include "SideChainRotamers.h"
|
|
|
|
// What the evaluator needs of the data: the observed rows at the scale, the solvent and the likelihood's parameters
|
|
// of the last fit. F_model(row) = k_total (F_atoms + fmask).
|
|
struct FieldReflections {
|
|
std::vector<std::array<float, 3>> hkl;
|
|
std::vector<float> stol2; // (sin theta / lambda)^2
|
|
std::vector<float> fo, d, var;
|
|
std::vector<char> centric, work; // work: not a free reflection
|
|
std::vector<float> k_total;
|
|
std::vector<std::complex<float>> fmask; // scaled
|
|
size_t Size() const { return hkl.size(); }
|
|
};
|
|
|
|
// An atom of a state: fractional position, isotropic B, occupancy, and its element's entry in the form-factor table.
|
|
struct FieldAtom {
|
|
float x, y, z, b, occ;
|
|
int element;
|
|
};
|
|
|
|
// A set of side-chain states, each a list of atoms (CSR: state s is atoms[start[s]..start[s+1])), and the
|
|
// combinations evaluated: each the states (one per copy of a residue) put in place of the current ones, F =
|
|
// F_total - sum dF(current) + sum dF(combination).
|
|
struct FieldStates {
|
|
std::vector<FieldAtom> atoms;
|
|
std::vector<int> start = {0};
|
|
std::vector<int> current;
|
|
std::vector<int> combo_states;
|
|
std::vector<int> combo_start = {0};
|
|
void Add(const std::vector<FieldAtom> &a) {
|
|
atoms.insert(atoms.end(), a.begin(), a.end());
|
|
start.push_back(static_cast<int>(atoms.size()));
|
|
}
|
|
void AddCombo(const std::vector<int> &states) {
|
|
combo_states.insert(combo_states.end(), states.begin(), states.end());
|
|
combo_start.push_back(static_cast<int>(combo_states.size()));
|
|
}
|
|
size_t Count() const { return start.size() - 1; }
|
|
size_t Combos() const { return combo_start.size() - 1; }
|
|
};
|
|
|
|
// The IT92 form factor of an element: c + sum a_i exp(-b_i stol2), as a0..a3 b0..b3 c.
|
|
using FormFactor = std::array<float, 9>;
|
|
|
|
// -ln L over the working reflections of F_total with one residue's side chain (or the copies of one) taken from
|
|
// its current states to each combination of states, by direct summation of the states' atoms over the group's
|
|
// operators.
|
|
class SideChainFieldEvaluator {
|
|
public:
|
|
virtual ~SideChainFieldEvaluator() = default;
|
|
// F of the model's atoms at the rows, as the refinement's engine computes them: what the field starts from.
|
|
virtual void SetTotal(const std::vector<std::complex<float>> &f) = 0;
|
|
// -ln L (work) per combination of `states`.
|
|
virtual std::vector<double> Evaluate(const FieldStates &states) = 0;
|
|
// The field moved to combination `to`: F_total += sum dF(to) - sum dF(current).
|
|
virtual void Move(const FieldStates &states, int to) = 0;
|
|
// The direct-summation F of one state's atoms at the rows (for checking the sum against the engine).
|
|
virtual std::vector<std::complex<float>> Contribution(const FieldStates &states, int s) = 0;
|
|
};
|
|
|
|
// The group's operators as the evaluator takes them: rotation (row-major) and translation, fractional.
|
|
std::vector<std::array<float, 12>> FieldOperators(const gemmi::SpaceGroup &sg);
|
|
|
|
// With `gpu`, the direct sums on the Apple GPU where there is one (SideChainFieldMetal.h, macOS): the same values,
|
|
// bit for bit.
|
|
std::unique_ptr<SideChainFieldEvaluator> MakeSideChainFieldEvaluatorCPU(const FieldReflections &refl,
|
|
const std::vector<std::array<float, 12>> &ops,
|
|
const std::vector<FormFactor> &elements,
|
|
size_t nthreads, bool gpu = false);
|
|
#ifdef JFJOCH_USE_CUDA
|
|
// The device memory the GPU evaluator takes at most for `rows` reflections under `n_ops` operators, bytes.
|
|
size_t SideChainFieldDeviceBytes(size_t rows, size_t n_ops);
|
|
// On `device`; throws JFJochException on a CUDA failure.
|
|
std::unique_ptr<SideChainFieldEvaluator> MakeSideChainFieldEvaluatorGPU(int device, const FieldReflections &refl,
|
|
const std::vector<std::array<float, 12>> &ops,
|
|
const std::vector<FormFactor> &elements);
|
|
// On every card of `devices`, the reflections split among them in contiguous parts that the cards evaluate side by
|
|
// side; on one card, the evaluator above.
|
|
std::unique_ptr<SideChainFieldEvaluator> MakeSideChainFieldEvaluatorGPUs(const std::vector<int> &devices,
|
|
const FieldReflections &refl,
|
|
const std::vector<std::array<float, 12>> &ops,
|
|
const std::vector<FormFactor> &elements);
|
|
#endif
|
|
|
|
// A residue the field moved: its atoms (index in the model's atom list) at their new positions, or absent.
|
|
struct SideChainFieldMove {
|
|
std::string name; // "LYS A87"
|
|
std::vector<double> chi_before, chi_after; // degrees (empty after: absent)
|
|
bool absent = false;
|
|
std::vector<std::pair<int, gemmi::Position>> atoms; // every atom of the residue beyond CB, hydrogens included
|
|
std::vector<int> pruned; // the atoms put to occupancy 0 (absent only)
|
|
double energy_gain = 0; // -ln L (work) units, the field's energy lowered by the move
|
|
};
|
|
|
|
// What a residue's best alternative would gain over the state as given, before the margin for the number of
|
|
// alternatives (for the log: a gain below the margin moves nothing).
|
|
struct SideChainFieldAlternative {
|
|
std::string name; // "LYS A87", "ASN A104 x3" for the copies
|
|
double gain = 0; // -ln L (work) units
|
|
std::vector<double> chi_given, chi_best; // degrees (empty best: absent); the first copy's
|
|
};
|
|
|
|
struct SideChainFieldResult {
|
|
int candidates = 0; // residues searched
|
|
std::vector<SideChainFieldAlternative> alternatives; // per variable, in the order searched
|
|
int sweeps = 0; // the first over every residue, the others over those near a move
|
|
bool copies_together = false; // the copies of a residue searched together only (the sweep budget)
|
|
double energy_before = 0, energy_after = 0;
|
|
std::vector<SideChainFieldMove> moves;
|
|
};
|
|
|
|
// `st`: the model as it is (hydrogens riding), with its cell and group; `element_of`: per atom in model order its
|
|
// entry in the form-factor table the evaluator was made with; `refinable`: per atom (RefinementTopology's);
|
|
// `ncs_group`: per residue (numbered over the model in order) the NCS group of its copies, -1 where it has none
|
|
// (or empty): the copies of a residue are one variable, searched in each rotamer together - the NCS restraints of
|
|
// the step after would pull a copy moved alone back - and each alone, for the copy whose environment differs (a
|
|
// crystal contact) where a sweep stays within its budget; `weight`: the X-ray term's weight in the refinement's target, which the repulsion term is
|
|
// divided by; `rows`: the evaluator's reflections. The residues searched: amino acids with a complete side chain, no alternative conformations, every
|
|
// atom at full occupancy, refinable and not bound by a LINK. `st` is left as it was; the moves say what changed.
|
|
SideChainFieldResult OptimiseSideChainField(const gemmi::Structure &st, const std::vector<int> &element_of,
|
|
const std::vector<char> &refinable, const std::vector<int> &ncs_group,
|
|
double weight, size_t rows, SideChainFieldEvaluator &evaluator);
|
|
|
|
// The state of the field's atoms of one residue (depth 2 and beyond, hydrogens included) at positions `p`, at full
|
|
// occupancy.
|
|
std::vector<FieldAtom> FieldAtomsOf(const gemmi::Residue &res, const SideChain &sc, const std::vector<gemmi::Position> &p,
|
|
const gemmi::UnitCell &cell, const std::vector<int> &element_of, int first_atom);
|