Gromacs  2025-dev-20241008-cf8b9ef
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
List of all members | Public Types | Public Member Functions

#include <gromacs/selection/nbsearch.h>

Description

Neighborhood searching for analysis tools.

See Neighborhood search for analysis tools for an overview.

To use the search, create an object of this type, call setCutoff() to initialize it, and then repeatedly call initSearch() to start a search with different sets of reference positions. For each set of reference positions, use methods in the returned AnalysisNeighborhoodSearch to find the reference positions that are within the given cutoff from a provided position.

initSearch() is thread-safe and can be called from multiple threads. Each call returns a different instance of the search object that can be used independently of the others. The returned AnalysisNeighborhoodSearch objects are also thread-safe, and can be used concurrently from multiple threads. It is also possible to create multiple concurrent searches within a single thread.

Todo:
Generalize the exclusion machinery to make it easier to use for other cases than atom-atom exclusions from the topology.
Examples:
template.cpp.

Public Types

enum  SearchMode { eSearchMode_Automatic, eSearchMode_Simple, eSearchMode_Grid }
 Searching algorithm to use. More...
 

Public Member Functions

 AnalysisNeighborhood ()
 Creates an uninitialized neighborhood search.
 
void setCutoff (real cutoff)
 Sets cutoff distance for the neighborhood searching. More...
 
void setXYMode (bool bXY)
 Sets the search to only happen in the XY plane. More...
 
void setTopologyExclusions (const ListOfLists< int > *excls)
 Sets atom exclusions from a topology. More...
 
void setMode (SearchMode mode)
 Sets the algorithm to use for searching. More...
 
SearchMode mode () const
 Returns the currently active search mode.
 
AnalysisNeighborhoodSearch initSearch (const t_pbc *pbc, const AnalysisNeighborhoodPositions &positions)
 Initializes neighborhood search for a set of positions. More...
 

Member Enumeration Documentation

Searching algorithm to use.

Enumerator
eSearchMode_Automatic 

Select algorithm based on heuristic efficiency considerations.

eSearchMode_Simple 

Use a simple loop over all pairs.

eSearchMode_Grid 

Use grid-based searching whenever possible.

Member Function Documentation

AnalysisNeighborhoodSearch gmx::AnalysisNeighborhood::initSearch ( const t_pbc pbc,
const AnalysisNeighborhoodPositions positions 
)

Initializes neighborhood search for a set of positions.

Parameters
[in]pbcPBC information for the frame.
[in]positionsSet of reference positions to use.
Returns
Search object that can be used to find positions from x within the given cutoff.
Exceptions
std::bad_allocif out of memory.

Currently, the input positions cannot use AnalysisNeighborhoodPositions::selectSingleFromArray().

Examples:
template.cpp.
void gmx::AnalysisNeighborhood::setCutoff ( real  cutoff)

Sets cutoff distance for the neighborhood searching.

Parameters
[in]cutoffCutoff distance for the search (<=0 stands for no cutoff).

Currently, can only be called before the first call to initSearch(). If this method is not called, no cutoff is used in the searches.

Does not throw.

Examples:
template.cpp.
void gmx::AnalysisNeighborhood::setMode ( SearchMode  mode)

Sets the algorithm to use for searching.

Parameters
[in]modeSearch mode to use.

Note that if mode is eSearchMode_Grid, it is still only a suggestion: grid-based searching may not be possible with the provided input, in which case a simple search is still used. This is mainly useful for testing purposes to force a mode.

Does not throw.

void gmx::AnalysisNeighborhood::setTopologyExclusions ( const ListOfLists< int > *  excls)

Sets atom exclusions from a topology.

The excls structure specifies the exclusions from test positions to reference positions, i.e., a block starting at excls->index[i] specifies the exclusions for test position i, and the indices in excls->a are indices of the reference positions. If excls->nr is smaller than a test position id, then such test positions do not have any exclusions. It is assumed that the indices within a block of indices in excls->a is ascending.

Does not throw.

See Also
AnalysisNeighborhoodPositions::exclusionIds()
void gmx::AnalysisNeighborhood::setXYMode ( bool  bXY)

Sets the search to only happen in the XY plane.

Z component of the coordinates is not used in the searching, and returned distances are computed in the XY plane. Only boxes with the third box vector parallel to the Z axis are currently implemented.

Does not throw.


The documentation for this class was generated from the following files: