Optimize the GPU pairlist of the selfcoordnum kernel

[HanatoK]

It looks like that the Github stacked PRs do not support PRs across forks, so I have to create this PR targeting master. This PR depends on #940.

This PR uses bit fields to store the pairlist data of selfcoordnum, and implements the pairlist in a tile-based manner. Specifically, the atoms are grouped in tiles, and the tile size matches the warp size (NVIDIA) or wavefront size (AMD) of the GPU. The following struct (see colvarcomp_coordnums_kernel.h) is used to record the interacting atom pairs between two tiles:

template <int tileSize>
struct TilePairMask {
  using PairMaskT = std::conditional_t<(tileSize <= 32), uint32_t, uint64_t>;
  PairMaskT pairMask[tileSize];
};

This design brings two benefits:

• Reduced memory footprint. For an atom group of 65,536 atoms, the CPU pairlist implementation would consume about 2 GiB of memory. The old GPU implementation has the same issue. After using the bit fields, the memory usage should drop to about 256 MiB.
• The original CPU pairlist implementation does not allow coalesced memory access. The new implementation does not only perform coalesced memory access, but also allows to check if all the atom pairs in an entire tile are non-interacting by warp-level primitives, and skip the non-interacting tiles easily.

To ensure the correctness, this PR also adds a new test of selfcoordnum with a large atom group "Protein" that has 104 atoms, and enable pairListFrequency 2 to verify the generation and use of pairlist.

[Copilot]

🟡 Changes recommended

The uninitialized pair mask can omit valid interactions, and the GPU test lacks intended gradient validation.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Optimizes GPU selfCoordNum pairlists with warp-sized tile bitmasks and adds a 104-atom regression test. Depends on PR #940.

Changes:

• Adds 32/64-lane tile masks and tiled GPU pairlist processing.
• Integrates tile-mask allocation and kernel dispatch.
• Adds large-pairlist trajectory, state, and force references.

File summaries

File	Description
tests/selfcoordnum-pairlist-large.in	Defines the large pairlist test.
tests/input_files/selfcoordnum-pairlist-large_harmonic-fixed/test.in	Configures the functional test; missing debugGradients on (moderate).
tests/input_files/selfcoordnum-pairlist-large_harmonic-fixed/AutoDiff/test_out.colvars.traj	Adds trajectory reference data.
tests/input_files/selfcoordnum-pairlist-large_harmonic-fixed/AutoDiff/test_out.colvars.state	Adds state reference data.
tests/input_files/selfcoordnum-pairlist-large_harmonic-fixed/AutoDiff/test_out_forces_4.dat	Adds step-4 force references.
tests/input_files/selfcoordnum-pairlist-large_harmonic-fixed/AutoDiff/test_out_forces_3.dat	Adds step-3 force references.
tests/input_files/selfcoordnum-pairlist-large_harmonic-fixed/AutoDiff/test_out_forces_2.dat	Adds step-2 force references.
tests/input_files/selfcoordnum-pairlist-large_harmonic-fixed/AutoDiff/test_out_forces_1.dat	Adds step-1 force references.
tests/input_files/selfcoordnum-pairlist-large_harmonic-fixed/AutoDiff/test_out_forces_0.dat	Adds step-0 force references.
tests/build_tests.sh	Registers the new test.
src/cuda/colvarcomp_coordnums_kernel.h	Defines tile masks and extends kernel APIs.
src/cuda/colvarcomp_coordnums_kernel.cu	Implements tiled processing; pairMaskSelf is used uninitialized (critical).
src/colvarcomp_coordnums.h	Tracks pairlist enablement.
src/colvarcomp_coordnums.cpp	Manages tile-mask memory and GPU execution.

Review details

Suppressed comments (1)

src/cuda/colvarcomp_coordnums_kernel.cu:822

• On pairlist rebuilds, pairMask reaches the bit-update at line 877 without any prior assignment. Because each update reads the previous value, the flattened tile mask stored at line 890 is indeterminate; initialize it to zero before populating it so subsequent reuse cannot skip valid pairs.

      PairMaskT pairMask;

• Files reviewed: 14/14 changed files
• Comments generated: 2
• Review effort level: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.