Gromacs  2026.0-dev-20241113-4b16639
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Neighborhood search for analysis tools

The header nbsearch.h declares a C++ interface to a relatively flexible and efficient neighborhood search. It is currently implemented within the selection module where it originated, but it does not have any dependencies on the other selection code and can be easily split out in the future.

The emphasis is on flexibility and ease of use; one main driver is to have one common implementation of grid-based searching to avoid replicating this in multiple tools (and to make more tools take advantage of the significant performance improvement this allows). The main features that it provides:

Usage

The neighborhood search works conceptually with two different sets of coordinates:

To start using the neighborhood search, you need to first create an instance of gmx::AnalysisNeighborhood. This class allows you to set some global properties for the search (most notably, the cutoff distance). Then you provide the reference positions as a gmx::AnalysisNeighborhoodPositions and PBC information to get a gmx::AnalysisNeighborhoodSearch instance. You can then either use methods directly in this class to find, e.g., the nearest reference point from a test position, or you can do a full pair search that returns you all the reference-test pairs within a cutoff. The pair search is performed using an instance of gmx::AnalysisNeighborhoodPairSearch that the search object returns. Methods that return information about pairs return an instance of gmx::AnalysisNeighborhoodPair, which can be used to access the indices of the reference and test positions in the pair, as well as the computed distance. See the class documentation for these classes for details.

For use together with selections, an instance of gmx::Selection or gmx::SelectionPosition can be transparently passed as the positions for the neighborhood search.

Implementation

This section provides a high-level overview of the algorithm used. It is not necessary to understand all the details to use the API, but it can be useful to get the best performance out of it. The main audience is developers who may need to extend the API to make it suitable for more cases.

The grid for the search is initialized based on the reference positions and the PBC information:

The average number of particles within a cell is somewhat heuristic in the above logic. This has not been particularly optimized for best performance.

When doing the search for test positions, each test position is considered independently: