Skip to content

feat(f3dock-nfft): add FastGaussianSum wrapper library with direct-evaluator reference (Phase 5 task 2)#32

Merged
transfix merged 1 commit into
masterfrom
feature/f3dock-phase5-nfft-fastsum
May 19, 2026
Merged

feat(f3dock-nfft): add FastGaussianSum wrapper library with direct-evaluator reference (Phase 5 task 2)#32
transfix merged 1 commit into
masterfrom
feature/f3dock-phase5-nfft-fastsum

Conversation

@transfix

Copy link
Copy Markdown
Owner

Summary

Adds a new static library f3dock-nfft exposing f3dock::nfft::FastGaussianSum, a thin wrapper that evaluates a 3D Gaussian sum

$$f(y_j) = \sum_{k=0}^{N-1} \alpha_k \cdot \exp(-c \cdot |y_j - x_k|^2)$$

at a batch of target points {y_j}. This is the building block that Phase 5 task 3 will route the F2Dock electrostatics gridding through under the nfftAccelerate opt-in flag landed in #31.

Two evaluation paths

  • evaluate_direct(out) — always-available O(N*M) reference loop. Used as ground truth in unit tests.
  • evaluate(out) — selects the NFFT3 fastsum fast path when is_accelerated() returns true; otherwise delegates to the direct evaluator. The NFFT3 hookup is intentionally a no-op fallback in this PR (so the library compiles and runs identically on every platform in the CI matrix) and lands in a follow-up patch once libnfft3 is available in CI.

Build / test plumbing

  • src/f3dock-nfft/CMakeLists.txt builds the static library and links the optional f3dock_science_stack INTERFACE target when present, so F2DOCK_HAVE_NFFT (and any related include/link plumbing) propagates automatically once libnfft3 is discovered.
  • Library is built under the existing F2DOCK_ENABLE_F3DOCK_EXPERIMENTAL gate alongside f3dock-domain / f3dock-flex / f3dock-icp / f3dock-loop-closure.
  • 7 new gtest cases in tests/unit/test_f3dock_nfft_fast_gaussian_sum.cpp lock in:
    • constructor validation (positive c, non-null sources)
    • direct evaluator vs a hand-written reference
    • evaluate() == evaluate_direct() bit-for-bit when unaccelerated
    • single-point identity bound
    • empty-source short-circuit
    • inspector accessors

Verification

  • cmake --build — green on WSL Ubuntu-24.04 / gcc-13
  • 197/197 unit tests pass (190 previous + 7 new)
  • clang-format-18 --Werror clean

Follow-ups

  • PR C (task 3): wire FastGaussianSum into the electrostatics gridding path in src/fft-utils/fastfft.cpp::gridding() under the nfftAccelerate switch; add integration smoke baseline.
  • PR D (task 4): libcvc geometry consumer audit (Blurmaps/GOA/PRGN).
  • Future: real NFFT3 fastsum hookup in evaluate() (requires libnfft3 in CI runners).

…aluator reference (Phase 5 task 2)

Adds a new static library 3dock-nfft exposing 3dock::nfft::FastGaussianSum, a thin wrapper that evaluates a 3D Gaussian sum f(y_j) = sum_k alpha_k * exp(-c * |y_j - x_k|^2). The wrapper has two evaluation paths:

  * evaluate_direct(out) -- always-available O(N*M) reference loop. Used as ground truth in unit tests.

  * evaluate(out) -- selects the NFFT3 fastsum fast path when is_accelerated() returns true; otherwise delegates to the direct evaluator. The NFFT3 hookup is intentionally a no-op fallback in this PR (so the library compiles and runs identically on every platform in the CI matrix) and lands in a follow-up patch once libnfft3 is available in CI.

This is the building block that Phase 5 task 3 will route the F2Dock electrostatics gridding through under the
fftAccelerate opt-in flag landed in PR #31.

Build / test plumbing:

  * src/f3dock-nfft/CMakeLists.txt builds the static library and links the optional 3dock_science_stack INTERFACE target when present, so F2DOCK_HAVE_NFFT (and any related include/link plumbing) propagates automatically once libnfft3 is discovered.

  * Library is built under the existing F2DOCK_ENABLE_F3DOCK_EXPERIMENTAL gate alongside 3dock-domain/3dock-flex/3dock-icp/3dock-loop-closure.

  * 7 new gtest cases in 	ests/unit/test_f3dock_nfft_fast_gaussian_sum.cpp lock in: constructor validation (positive c, non-null sources), direct evaluator vs a hand-written reference, evaluate()=evaluate_direct() bit-for-bit when unaccelerated, single-point identity bound, empty-source short-circuit, and inspector accessors.

Verification: 197/197 unit tests pass; clang-format-18 --Werror clean.
@transfix transfix merged commit 2dc94f6 into master May 19, 2026
10 checks passed
@transfix transfix deleted the feature/f3dock-phase5-nfft-fastsum branch May 19, 2026 15:14
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant