diff --git a/CLAUDE.md b/CLAUDE.md index d90043cb0..d3ecfc9d2 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -16,7 +16,7 @@ changing CLI behaviour, update the parser, that page and, for a basic option, th ## Build Out-of-source CMake build, C++20, heavy use of `FetchContent` (spdlog, zstd, HDF5, -slsDetectorPackage, Catch2, cpp-httplib, libzmq, libtiff, FFTW, Ceres (with abseil), zlib-ng and Eigen are +slsDetectorPackage, Catch2, cpp-httplib, libzmq, libtiff, Ceres (with abseil), zlib-ng and Eigen are downloaded and statically linked — the **first configure needs network access** and is slow; the fast-feedback indexer behind FFBIDX is vendored in `image_analysis/indexing/fast-feedback-indexer/`). **No library has to come from the host**: `zlib-devel`/`eigen3-devel` are no longer needed. @@ -38,8 +38,11 @@ make -j$(nproc) jfjoch_broker # the main service; build other targets by na Key CMake options: - `JFJOCH_USE_CUDA` (default ON) — GPU path. Needs CUDA ≥ 12.8 (older is warned about and ignored). Provides the `ffbidx` and `fft` GPU indexers; without it the indexers are the CPU `fftw` - and a CPU port of the fast-feedback indexer (`FFBIDXIndexerCPU`, always built). FFTW is fetched and - `JFJOCH_USE_FFTW` defined unconditionally, so `fftw` is always there. CUDA absence is not a build + and a CPU port of the fast-feedback indexer (`FFBIDXIndexerCPU`, always built). Every CPU FFT (the + `fftw` indexer, beam-centre search, tNCS, model maps, MR, the viewer's chart) goes through + `common/CpuFFT` on the pocketfft header vendored with gemmi - FFTW is no longer a dependency, the + `fftw`/`FFTW` name is kept for the CPU indexer only for back compatibility. pocketfft vectorises + with GCC/Clang vector extensions and runs scalar under MSVC. CUDA absence is not a build error — nvcc is looked for on `PATH`, `CUDA_PATH`, `CUDA_HOME`, `CUDA_ROOT`, `/usr/local/cuda` and `/opt/cuda`. - `JFJOCH_WRITER_ONLY` (default OFF) — builds only the HDF5 writer (with the detector control, @@ -393,7 +396,7 @@ CXX_THREADS). The indexer is chosen with `-X` (`Auto|FFT|cuFFT|FFTW|FFBIDX|None`, default `Auto`, which resolves to a GPU indexer when one is present and `fftw` otherwise): `ffbidx` wants a known cell (`-C`) and suits sparse serial stills; `fft` indexes de novo and suits strong rotation data - it is the algorithm, run -with cuFFT on a GPU and with FFTW without one (or under `--no-gpu`), while `cufft`/`fftw` name one +with cuFFT on a GPU and with pocketfft without one (or under `--no-gpu`), while `cufft`/`fftw` name one implementation each. Only rugnux's CLI spells it this way: internally (and in the broker's OpenAPI) `FFT` is the GPU implementation, which the CLI's `cufft` maps onto. diff --git a/CMakeLists.txt b/CMakeLists.txt index eae9a9287..88e03e81b 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -474,45 +474,6 @@ FetchContent_Declare(tiff EXCLUDE_FROM_ALL) FetchContent_MakeAvailable(tiff) -# 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) -# SIMD codelets are runtime-dispatched (cpuid), so enabling AVX2 does NOT require an AVX2 CPU -# -- FFTW falls back at runtime. The codelet sets are arch-specific, so guard by processor: -# x86 gets SSE2/AVX/AVX2, aarch64 (Apple Silicon, Grace on DGX Spark) gets NEON - added below the -# FetchContent, as FFTW's CMake build has no switch for it; other arches build scalar. -IF (CMAKE_SYSTEM_PROCESSOR MATCHES "x86_64|AMD64|amd64") - SET(ENABLE_SSE2 ON CACHE BOOL "" FORCE) - SET(ENABLE_AVX ON CACHE BOOL "" FORCE) - SET(ENABLE_AVX2 ON CACHE BOOL "" FORCE) -ENDIF() -FetchContent_Declare(fftw - URL https://www.fftw.org/fftw-3.3.10.tar.gz - URL_HASH SHA256=56c932549852cddcfafdab3820b0200c7742675be92179e59e6215b340e26467 - EXCLUDE_FROM_ALL) -FetchContent_MakeAvailable(fftw) -# FFTW exposes fftw3.h only via $, so consuming fftw3f straight from -# the build tree (FetchContent) leaves the header unreachable. On Linux a system-installed -# fftw3.h masks this; on Windows it does not. Add the source-tree api/ dir for build-tree use. -TARGET_INCLUDE_DIRECTORIES(fftw3f INTERFACE $) -# NEON: only FFTW's autotools build knows it (--enable-neon); its CMake build silently builds scalar -# code on ARM (and ignores an ENABLE_NEON, as this file once set). So the NEON codelets are added -# the way its CMakeLists adds the SSE2/AVX ones: the sources, and HAVE_NEON so that dft/conf.c and -# rdft/conf.c register them - as a definition, because its config.h template carries HAVE_NEON only -# as a comment. NEON is part of every aarch64 CPU, so no compiler flag is needed. It is single -# precision, which is all that is built here. Measured on Apple Silicon against the scalar build -# (same results to 1e-8): the indexer's batched 1D r2c 1.8x faster at a power-of-two length and 1.3x -# at 730, the 2D r2c of the beam-centre search 1.9x, a 128^3 c2r map 2.6x. -IF (CMAKE_SYSTEM_PROCESSOR MATCHES "aarch64|arm64|ARM64") - FILE(GLOB _fftw_neon_sources ${fftw_SOURCE_DIR}/dft/simd/neon/*.c ${fftw_SOURCE_DIR}/rdft/simd/neon/*.c) - TARGET_SOURCES(fftw3f PRIVATE ${_fftw_neon_sources}) - TARGET_COMPILE_DEFINITIONS(fftw3f PRIVATE HAVE_NEON=1) -ENDIF() -ADD_COMPILE_DEFINITIONS(JFJOCH_USE_FFTW) - # Eigen (header-only), consumed by the analysis libraries (the vendored fast-feedback indexer among them) # directly and by Ceres through its own find_package(Eigen3). The headers are fetched here and a two-file config package for # them is written into the build tree; Eigen3_DIR then points at it, so every find_package(Eigen3) diff --git a/THIRD_PARTY_NOTICES.md b/THIRD_PARTY_NOTICES.md index eb27cc3b6..c17cecad7 100644 --- a/THIRD_PARTY_NOTICES.md +++ b/THIRD_PARTY_NOTICES.md @@ -26,7 +26,6 @@ linked into the Jungfraujoch executables. | [cpp-httplib](https://github.com/yhirose/cpp-httplib) | 0.56.0 | Yuji Hirose | MIT | [cpp-httplib.txt](licenses/cpp-httplib.txt) | | [libzmq (ZeroMQ)](https://github.com/zeromq/libzmq) | 4.3.5 | iMatix and contributors | MPL-2.0 | [libzmq.txt](licenses/libzmq.txt) | | [libtiff](https://gitlab.com/libtiff/libtiff) | 4.7.2 | Sam Leffler; SGI | libtiff (BSD-like) | [libtiff.txt](licenses/libtiff.txt) | -| [FFTW](https://www.fftw.org/) | 3.3.10 | Matteo Frigo; MIT | GPL-2.0-or-later | [fftw.txt](licenses/fftw.txt) | | [Ceres Solver](https://github.com/ceres-solver/ceres-solver) | commit 0c70ed3a1a2d | Google Inc. and contributors | BSD-3-Clause | [ceres-solver.txt](licenses/ceres-solver.txt) | | [Abseil](https://github.com/abseil/abseil-cpp) | 20250127 (required by Ceres) | Google Inc. | Apache-2.0 | [abseil.txt](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](licenses/mbedtls.txt), [tf-psa-crypto.txt](licenses/tf-psa-crypto.txt) | @@ -80,7 +79,7 @@ These live in the source tree (see the path) rather than being fetched; traccc, | [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](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](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](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](licenses/gemmi.txt) | +| [GEMMI](https://github.com/project-gemmi/gemmi) (adapted) | `image_analysis/structure_refinement/ModelScaling.cpp`, `ModelMaskGPU.cu`, `ModelStructureFactorsGPU.cpp`, `ModelDensityMetal.metal`, `AtomGradientMetal.metal` | Global Phasing Ltd. | MPL-2.0 | [gemmi.txt](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](licenses/durin.txt) | | [xbflash.qspi](https://github.com/Xilinx/XRT) | `tools/xbflash.qspi/` | Xilinx / AMD | Apache-2.0 | [xbflash-qspi.txt](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](licenses/wingetopt.txt) | @@ -154,8 +153,8 @@ served frontend, so the shipped web UI carries its own attribution. `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. + `ModelStructureFactorsGPU.cpp`, `ModelDensityMetal.metal` and `AtomGradientMetal.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 @@ -163,7 +162,6 @@ served frontend, so the shipped web UI carries its own attribution. * **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 diff --git a/common/CpuFFT.cpp b/common/CpuFFT.cpp index 6085fc0d3..cef90287a 100644 --- a/common/CpuFFT.cpp +++ b/common/CpuFFT.cpp @@ -6,6 +6,11 @@ // 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 +// MSVC: the scalar code (pocketfft vectorises only with the GCC/Clang vector extension, and decides so +// itself; said here so that it stays so). +#ifdef _MSC_VER +#define POCKETFFT_NO_VECTORS +#endif #include "../gemmi_gph/gemmi/third_party/pocketfft_hdronly.h" namespace cpu_fft { diff --git a/common/Logger.cpp b/common/Logger.cpp index cccee71f4..52c95c625 100644 --- a/common/Logger.cpp +++ b/common/Logger.cpp @@ -53,9 +53,7 @@ Logger::Logger(const std::string &service_name, const std::string &file_name) { #ifdef JFJOCH_USE_CUDA variant += "C"; #endif -#ifdef JFJOCH_USE_FFTW variant += "F"; -#endif std::vector sinks; sinks.push_back(std::make_shared()); diff --git a/docker/ubuntu2404/Dockerfile b/docker/ubuntu2404/Dockerfile index c84fc9d38..046e6f304 100644 --- a/docker/ubuntu2404/Dockerfile +++ b/docker/ubuntu2404/Dockerfile @@ -162,7 +162,7 @@ ENV CMAKE_PREFIX_PATH=/opt/qt-${QT_VERSION}-static:/opt/dbus-${DBUS_VERSION}-sta # qemu-user-static HDF5 runs two try_run() probes (config/ConfigureChecks.cmake) that # need CMAKE_CROSSCOMPILING_EMULATOR. libzmq guards its own run-checks # with NOT CMAKE_CROSSCOMPILING; Ceres, libtiff, zstd, Catch2, spdlog, -# cpp-httplib, FFTW and ffbidx have no run-checks at all. +# cpp-httplib and ffbidx have no run-checks at all. # binutils-aarch64-linux-gnu reading aarch64 ELF on the build host. # :arm64 libraries ZLIB is one of the project's two external dependencies (Eigen, the # other, is header-only and installed above); OpenSSL is needed by the diff --git a/docker/ubuntu2404/aarch64-sbsa.cmake b/docker/ubuntu2404/aarch64-sbsa.cmake index 3c4f76841..cd4b90095 100644 --- a/docker/ubuntu2404/aarch64-sbsa.cmake +++ b/docker/ubuntu2404/aarch64-sbsa.cmake @@ -9,7 +9,7 @@ # /usr/lib/aarch64-linux-gnu and headers are shared in /usr/include, so CMAKE_LIBRARY_ARCHITECTURE # is what steers find_library() rather than CMAKE_SYSROOT. set(CMAKE_SYSTEM_NAME Linux) -set(CMAKE_SYSTEM_PROCESSOR aarch64) # also selects FFTW's NEON codelets in CMakeLists.txt +set(CMAKE_SYSTEM_PROCESSOR aarch64) set(CMAKE_C_COMPILER aarch64-linux-gnu-gcc) set(CMAKE_CXX_COMPILER aarch64-linux-gnu-g++) diff --git a/docs/CPU_DATA_ANALYSIS_DECISIONS.md b/docs/CPU_DATA_ANALYSIS_DECISIONS.md index fae331bb5..574bbdcee 100644 --- a/docs/CPU_DATA_ANALYSIS_DECISIONS.md +++ b/docs/CPU_DATA_ANALYSIS_DECISIONS.md @@ -275,7 +275,7 @@ The refinement walks a coarse-to-fine ladder, 6 Å → 4.5 Å → 3.5 Å, each z The refinement sees **only the working reflections**. The step is then committed only if it lowers **R-free**, computed at full resolution on the free set it never saw; otherwise the model is put back exactly where it was read and the maps are the ones it would have given. The whole addition costs about two seconds. Note that the origin is a gauge in some space groups — free in all three directions in $P1$, and along the unique axis in a polar group — so those components of the translation are undetermined; nothing is done about that beyond the Levenberg–Marquardt damping and the R-free gate, which between them make an undetermined direction harmless rather than unstable. -Where a CUDA GPU is present, the refinement's target is evaluated on it: the same density, the same composition of $F_\mathrm{calc}$ from one copy of the model, the same bulk-solvent mask with its islands removed, the same scale fit and the same Jacobian, computed on the device, where a fit takes a fraction of a second rather than several seconds. The device is chosen once per validation, before anything is computed, and never revisited - the real fit and every replicate of the null of §14.5 on the same one. What goes on the GPU is decided for all parts at once, on one budget: 80% of the card's total memory (judged on the total, so the same input on the same machine always takes the same path), less what a merge still at work holds there. Every engine is reserved up front and kept to the end, so it is their sum that has to fit: the structure factors to the data's resolution (which also make the maps), one rigid-body engine, the null's structure factors to its coarser limit and one engine for the scale fits of §14.2 each take their place in that order where they still fit, and more rigid-body engines and then more scale-fit engines are added only within half of the budget: they change only how many fits run at once, and on a large cell, where one fit already fills the card, they buy little. A part that does not fit, or a cell too small for the GPU's gridding, runs on the CPU, as everything does where there is no GPU. A CUDA failure ends the validation, not the run: the validation reports why it did not finish, decides nothing, and the reflection files are those of a run without a model. The two agree to rounding and not bit for bit: the device measures distances in single precision and transforms with cuFFT instead of FFTW, and GEMMI's scale fit, whose stopping rule leaves it unconverged at about $10^{-4}$ of $|F|$, can respond to that rounding with a step of its own. A rigid-body step accepted or rejected on an R-free difference below about $5\cdot10^{-4}$ can therefore go either way between the two; every kernel is deterministic, so either one gives the same answer on every run. +Where a CUDA GPU is present, the refinement's target is evaluated on it: the same density, the same composition of $F_\mathrm{calc}$ from one copy of the model, the same bulk-solvent mask with its islands removed, the same scale fit and the same Jacobian, computed on the device, where a fit takes a fraction of a second rather than several seconds. The device is chosen once per validation, before anything is computed, and never revisited - the real fit and every replicate of the null of §14.5 on the same one. What goes on the GPU is decided for all parts at once, on one budget: 80% of the card's total memory (judged on the total, so the same input on the same machine always takes the same path), less what a merge still at work holds there. Every engine is reserved up front and kept to the end, so it is their sum that has to fit: the structure factors to the data's resolution (which also make the maps), one rigid-body engine, the null's structure factors to its coarser limit and one engine for the scale fits of §14.2 each take their place in that order where they still fit, and more rigid-body engines and then more scale-fit engines are added only within half of the budget: they change only how many fits run at once, and on a large cell, where one fit already fills the card, they buy little. A part that does not fit, or a cell too small for the GPU's gridding, runs on the CPU, as everything does where there is no GPU. A CUDA failure ends the validation, not the run: the validation reports why it did not finish, decides nothing, and the reflection files are those of a run without a model. The two agree to rounding and not bit for bit: the device measures distances in single precision and transforms with cuFFT instead of pocketfft, and GEMMI's scale fit, whose stopping rule leaves it unconverged at about $10^{-4}$ of $|F|$, can respond to that rounding with a step of its own. A rigid-body step accepted or rejected on an R-free difference below about $5\cdot10^{-4}$ can therefore go either way between the two; every kernel is deterministic, so either one gives the same answer on every run. The rotation and translation actually taken are reported (`RIGID_BODY_ROTATION_DEG`, `RIGID_BODY_SHIFT_A`), together with the R-free before it (`R_FREE_BEFORE_RIGID_BODY`), so what the placement bought is visible. diff --git a/docs/CPU_DATA_ANALYSIS_IMAGE.md b/docs/CPU_DATA_ANALYSIS_IMAGE.md index ca528af07..ddac0f395 100644 --- a/docs/CPU_DATA_ANALYSIS_IMAGE.md +++ b/docs/CPU_DATA_ANALYSIS_IMAGE.md @@ -182,7 +182,7 @@ margin, not a centre: the surface can be locally flat over tens of pixels, and t peak-to-runner-up margin says so. A **local walk** is then seeded at the capture and refines it; where it declines there it is started again from the file's centre, and only where neither start gives it something to fit does the capture stand alone. The transforms run on the GPU where one is present and -they fit half of the card's total memory, and on FFTW otherwise, with everything that decides anything +they fit half of the card's total memory, and on the CPU FFT (pocketfft) otherwise, with everything that decides anything shared between the two. The run log then carries: diff --git a/docs/CPU_DATA_ANALYSIS_INDEXING.md b/docs/CPU_DATA_ANALYSIS_INDEXING.md index aa83b6b9a..7fac4ebb2 100644 --- a/docs/CPU_DATA_ANALYSIS_INDEXING.md +++ b/docs/CPU_DATA_ANALYSIS_INDEXING.md @@ -295,6 +295,13 @@ re-checks, about a second each. The checks taken on the pre-pass frames - the geometry walk's refits, the metric-symmetry arm and the pre-pass spot-crowding count - stay on those frames in both modes, and their near ties are re-checked once every frame is in on both. +A lattice is promoted to a centred or higher class on its metric alone, and the geometry and +integration are then held to that class. Where the space-group search afterwards finds no symmetry +at all (P 1) on such a lattice, the constraint has nothing left behind it, so a stored rotation run +is made once more with the lattice held triclinic from its first pass (as `-S P1` holds it), and of +the two merges the one whose CC1/2, averaged per resolution shell on Fisher's $z$, is higher is the +answer. + **A first pass that ends with no usable lattice tries a leaner, shallower one.** A crystal sitting in a crystalline powder floods the pass with spots that are not its own — measured, 2112 spots a frame against the 80 a clean crystal on the same beamline gives — and the FFT then takes its cell out of the diff --git a/docs/GPU_DATA_ANALYSIS.md b/docs/GPU_DATA_ANALYSIS.md index 82343dbdb..18d66d690 100644 --- a/docs/GPU_DATA_ANALYSIS.md +++ b/docs/GPU_DATA_ANALYSIS.md @@ -12,7 +12,7 @@ computes. The methods themselves are described once, in the (`JFJOCH_USE_CUDA=OFF`) runs the whole pipeline on it, the `ffbidx` indexer included (an in-tree CPU port of the library's kernels). How closely the two agree is stated engine by engine below and in the source: where the arithmetic is integer, or the order of every sum is fixed to -the host's, the result is the same to the bit; where the GPU uses float distances, cuFFT for FFTW, or a +the host's, the result is the same to the bit; where the GPU uses float distances, cuFFT for pocketfft, or a different (fixed) summation order, the two agree to rounding. Every engine is deterministic on its own - no floating-point atomics decide a result - so the same input gives the same output on every run of a GPU build. @@ -74,7 +74,7 @@ nothing. stays on the host. [§1.4](CPU_DATA_ANALYSIS_IMAGE.md#14-the-beam-centre) - **Beam centre by FFT** (`BeamCenterFFTGPU.cu`) - the self-convolutions that score every candidate centre at once, their combination into one score surface, and the shortlist of its peaks, with only - the shortlist brought back. Runs on FFTW on the host instead where it would need more than half of + the shortlist brought back. Runs on the CPU FFT on the host instead where it would need more than half of the card's total memory, decided before the card is touched and logged. [§1.4](CPU_DATA_ANALYSIS_IMAGE.md#14-the-beam-centre) @@ -158,7 +158,7 @@ total and not on what is free, the same input on the same card always takes the The model's structure factors and the rigid body run on the card where there is one, every part placed on it or on the CPU up front against one budget, 80% of the card's total memory ([§14.8](CPU_DATA_ANALYSIS_DECISIONS.md#148-rigid-body-placement-of-the-model)); the GPU and CPU -agree to rounding (float distances, cuFFT for FFTW, the crystal's symmetry composed in reciprocal +agree to rounding (float distances, cuFFT for pocketfft, the crystal's symmetry composed in reciprocal space instead of by symmetrizing the grid). On a machine with several cards, the rigid-body engines the first card has no room for go on the others, each against its own budget. @@ -217,7 +217,7 @@ reflections, the grids, the symmetry and the restraints resident, and per evalua positions up and one value and one gradient per atom back. Everything that depends on the cell, the group and the reflections - the grids, the operators, the adjoint's lists - is worked out once on the host with gemmi when the engine is made. The GPU and CPU engines compute the same target to rounding (float distances and densities, -cuFFT for FFTW, summation order); the GPU's result is the same from run to run, as no sum of a result is a +cuFFT for pocketfft, summation order); the GPU's result is the same from run to run, as no sum of a result is a floating-point atomic: every per-point, per-reflection and per-atom sum is a gather in a fixed order, and every total a `cub::DeviceReduce` tree, whose order for a given size is fixed. @@ -342,7 +342,7 @@ mask 15-18% at low resolution. Inside a full `rugnux --model` run of a 5,000-ato ## Apple GPUs (Metal) -A macOS build has no CUDA, and three engines run on the Apple GPU instead (none under +A macOS build has no CUDA, and six engines run on the Apple GPU instead (none under `rugnux --no-gpu`; where the GPU fails, the CPU takes over with a warning): - **Bragg integration** (`BraggIntegrationEngineMetal.mm`, `.metal`) - the CPU engine with its @@ -358,6 +358,15 @@ A macOS build has no CUDA, and three engines run on the Apple GPU instead (none for model validation and molecular replacement, as a gather over bricks of the grid as under CUDA; the same grid as the CPU's **to the bit**. [§14.1](CPU_DATA_ANALYSIS_DECISIONS.md#141-model-structure-factors) +- **Refinement gradient** (`AtomGradientMetal.mm`, `.metal`) - the sums of the CPU refinement + engine's gradient over the FFT method's map, each atom's box walked by one SIMD group as under CUDA; + the CPU's points, summed in single precision, so the gradient is the CPU's to a few parts in 1e5 + (a macOS CI step checks it against the CPU's). It halves the time of a refinement on the CPU engine. +- **Side-chain field** (`SideChainFieldMetal.mm`, `.metal`) - the direct sums of every side-chain state's + structure factors over the reflections, one thread per reflection and state; the CPU's sums **to the bit** + (the B factor's exp is `BraggExp.h` on both), which a macOS CI step checks. +- **Bulk-solvent mask shrink** (`ShrinkMaskMetal.mm`, `.metal`) - the mask's shrink by the 0.8 Å radius, + one thread per grid point; the same mask as the CPU's **to the bit**, which a macOS CI step checks. - **Molecular-replacement rotation function** (`MolecularReplacementMetal.mm`, `.metal`) - the rotation function's trial orientations scored from a copy of the molecular transform; equal to the CPU's to rounding. diff --git a/docs/RUGNUX_ADVANCED.md b/docs/RUGNUX_ADVANCED.md index 586f316f0..53ec4405c 100644 --- a/docs/RUGNUX_ADVANCED.md +++ b/docs/RUGNUX_ADVANCED.md @@ -329,8 +329,8 @@ rocking curve merged with are the first file's; the ice-ring gate pools the fram The files must be of one crystal: each file's cell the first's lattice (in its setting or another) and the same space group. A run stops with a message naming both cells, or both groups, where they are not - -unless the cell is given (`-C`, or a reference `-z`) and, for the group, `-S`: then everything is merged -in what is given, and the crystals of a file not on that cell are left out. A mix of stills and rotation +unless the cell is given (`-C`, or a reference `-z`) and, for the group, `-S` (or the group of a reference +`-z` that states one): then everything is merged in what is given, and the crystals of a file not on that cell are left out. A mix of stills and rotation files is refused, and so are several rotation files (`--mode scale` merges one sweep at a time; several sweeps of one crystal are merged together from their masters by `--mode mx`). Under `--force-still` a rotation file counts as stills. `-s`/`-e` select images of one file and are refused with several. The diff --git a/docs/RUGNUX_CLI.md b/docs/RUGNUX_CLI.md index 47f6ede82..a85be37f6 100644 --- a/docs/RUGNUX_CLI.md +++ b/docs/RUGNUX_CLI.md @@ -61,7 +61,8 @@ Refines a model against merged data that already exist - an MTZ or a structure-f reads no images. The model is required, given among the inputs or with `--model`. Without `--mode`, rugnux takes `--mode refine` when the inputs hold reflections and no images and a model is given - among the inputs or with `--model` (`rugnux -o refined data.mtz model.cif`, -`rugnux -o refined --model model.cif data.mtz`). A restraint dictionary for a ligand can be given among the +`rugnux -o refined --model model.cif data.mtz`); the reflections are an input then, not `-z`, which `--mode refine` +does not use (a reflection file given only with `-z` does not select it). A restraint dictionary for a ligand can be given among the inputs as well (`--restraints`) ([Refining a model against structure factors](RUGNUX_MODEL_AND_REFERENCE.md#refining-a-model-against-structure-factors-rugnux---mode-refine)). @@ -280,12 +281,12 @@ For very long axes the direction grid's angular resolution binds well below 500 | Option | Description | | --- | --- | | `--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 | +| `-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 (`FFTW` keeps its old name: the CPU transforms are pocketfft's); `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 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 | +| `-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 this cell and `-S P1`. The lattice is indexed in that system, never above or below it, on the axes of the cell as typed (an F- or R-centred one in its conventional setting), 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 | +| `-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)). Without `-C` the group fixes only the symmetry, not the cell: the lattice is found and reduced as in a run without `-S` (a supercell the indexer returns is still stepped down to the crystal's cell, a long axis is still looked for), indexing puts the crystal in the group's own Bravais class, nothing promotes or demotes it past that class, and the group is applied to the cell found, in its conventional setting. With `-C` as well, the lattice and its setting are the ones given and nothing reduces or doubles the cell. 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`, the cell is written on the given cell's axes | | `-r, --geom-refine ` | Geometry refinement: `none` \| `orientation` \| `beam_and_lattice` (default; on rotation data restrained toward the sweep's geometry, [§7.4](CPU_DATA_ANALYSIS_INDEXING.md#74-multi-stage-tightening-of-inlier-tolerance)) \| `flex` (try all three per image, keep whichever indexes the most spots; alias `multi`) | | `-R, --two-pass-rotation[=num]` | Two-pass offline rotation indexing (default for goniometer data; optional first-pass image count, default 100) | | `--force-rotation-lattice ` | Force rotation lattice (9 floats, Å), skipping the first pass | @@ -331,10 +332,9 @@ 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